Sigma Computing Data Models API

openapi: 3.2.0
info:
  title: Sigma Computing Data Models API
  version: '1.0'
  description: 'Operations tagged dataModels across 3 of this provider''s published API definitions: sigma-computing-code-representation-openapi.yaml, sigma-computing-public-rest-api-openapi.json, sigma-computing-rest-api-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sigmacomputing.com
  description: Server for GCP (US) hosted organizations
- url: https://api.sa.gcp.sigmacomputing.com
  description: Server for GCP (KSA) hosted organizations
- url: https://aws-api.sigmacomputing.com
  description: Server for AWS US (West) hosted organizations
- url: https://api.us-a.aws.sigmacomputing.com
  description: Server for AWS US (East) hosted organizations
- url: https://api.ca.aws.sigmacomputing.com
  description: Server for AWS Canada hosted organizations
- url: https://api.eu.aws.sigmacomputing.com
  description: Server for AWS Europe hosted organizations
- url: https://api.au.aws.sigmacomputing.com
  description: Server for AWS Australia and APAC hosted organizations
- url: https://api.uk.aws.sigmacomputing.com
  description: Server for AWS UK hosted organizations
- url: https://api.us.azure.sigmacomputing.com
  description: Server for Azure US hosted organizations
- url: https://api.eu.azure.sigmacomputing.com
  description: Server for Azure Europe hosted organizations
- url: https://api.ca.azure.sigmacomputing.com
  description: Server for Azure Canada hosted organizations
- url: https://api.uk.azure.sigmacomputing.com
  description: Server for Azure United Kingdom hosted organizations
- url: https://api.au.azure.sigmacomputing.com
  description: Server for Azure Australia hosted organizations
tags:
- name: dataModels
paths:
  /v2/dataModels/{dataModelId}/spec:
    get:
      operationId: getDataModelSpec
      summary: Get the code representation of a data model
      description: 'This endpoint returns a code representation of an existing data model, including metadata and contents. The response can be formatted as either JSON or YAML, and contains a data model''s pages, elements, columns, sources, and more. The representation can be used to store, copy, or modify the data model programmatically.


        For more information on managing data models via the Sigma API, see [Manage data models as code](https://help.sigmacomputing.com/docs/manage-data-models-as-code). For more information on using this endpoint, including an end-to-end example, see [Get the code representation of a data model](https://help.sigmacomputing.com/docs/get-the-code-representation-of-a-data-model).


        ### Usage notes

        - To perform this operation, you must use API credentials owned by a user with **Can view** access to the data model.

        - Retrieve the **dataModelId** by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint. Invalid or nonexistent IDs return an error.

        - The response includes the data sources, metadata, and relationships necessary to recreate the data model. The data itself is not included in the response.

        - To create a new data model from code, use the [/v2/dataModels/spec](https://help.sigmacomputing.com/reference/create-data-model-spec) endpoint.

        - To update an existing data model from code, use the [/v2/dataModels/{dataModelId}/spec](https://help.sigmacomputing.com/reference/update-data-model-spec) endpoint.

        - The default format of the representation is JSON. To receive YAML, add the query parameter `?format=yaml` or the header `Accept: application/yaml`.


        ### Usage scenarios

        - **Backup and restore**: Developers can use this endpoint to programmatically back up data models and restore them if needed.

        - **Version control**: Developers can use this endpoint to programmatically manage, update, and version control data models between several organizations or tenants.

        - **Administration**: Administrators can use this endpoint to programmatically analyze and govern data models across an organization.

        - **Migration**: Administrators can use this endpoint to programmatically migrate data models between organizations or tenants.

        - **Agentic workflows**: Agents can use these endpoints to directly manage data model contents in code.

        '
      tags:
      - dataModels
      parameters:
      - name: dataModelId
        in: path
        required: true
        schema:
          type: string
      - name: documentVersion
        in: query
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataModelSpec'
    put:
      operationId: updateDataModelSpec
      summary: Update a data model from a code representation
      description: 'This endpoint replaces a data model with the contents defined in a code representation. You can programmatically update the data model''s structure, metadata, and contents. This creates a new version of the data model, which is accessible from the Sigma UI.


        For more information on managing data models via the Sigma API, see [Manage data models as code](https://help.sigmacomputing.com/docs/manage-data-models-as-code). For more information on using this endpoint, including an end-to-end example, see [Update a data model from a code representation](https://help.sigmacomputing.com/docs/update-a-data-model-from-a-code-representation).


        ### Usage notes

        - To perform this operation, you must use API credentials owned by a user assigned an account type with **Create, edit, and publish data models** permission.

        - To perform this operation, you must use API credentials owned by a user with **Can edit** access to the data model.

        - Retrieve a representation of an existing data model by calling the [/v2/dataModels/{dataModelId}/spec](https://help.sigmacomputing.com/reference/get-data-model-spec) endpoint.

        - To create a new data model from code, use the [/v2/dataModels/spec](https://help.sigmacomputing.com/reference/create-data-model-spec) endpoint.

        - The endpoint only supports updates to the `pages` array and its contents. Additional fields are not required and are ignored in the request body.

        - When `documentVersion` is provided in the request body, the update fails when the data model 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 data model in the request body.

        - The default format of the representation is JSON. To use YAML, add the header `Content-Type: application/yaml`.


        ### Usage scenarios

        - **Automation**: If you want to update several data models across one or more organizations, or in response to external events, you can use this endpoint to programmatically update the data models.

        - **Integration**: Using this endpoint, you can update data models based on external data sources or integrate Sigma with other tools and platforms.

        - **Version control**: Developers can use this endpoint to programmatically manage, update, and version control data models between several organizations or tenants.

        - **Agentic workflows**: Agents can use these endpoints to directly manage data model contents in code.

        '
      tags:
      - dataModels
      parameters:
      - name: dataModelId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataModels_updateDataModelSpec_Response_200'
      requestBody:
        description: The request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataModelSpec'
    servers:
    - url: https://api.sigmacomputing.com
      description: Server for GCP (US) hosted organizations
    - url: https://api.sa.gcp.sigmacomputing.com
      description: Server for GCP (KSA) hosted organizations
    - url: https://aws-api.sigmacomputing.com
      description: Server for AWS US (West) hosted organizations
    - url: https://api.us-a.aws.sigmacomputing.com
      description: Server for AWS US (East) hosted organizations
    - url: https://api.ca.aws.sigmacomputing.com
      description: Server for AWS Canada hosted organizations
    - url: https://api.eu.aws.sigmacomputing.com
      description: Server for AWS Europe hosted organizations
    - url: https://api.au.aws.sigmacomputing.com
      description: Server for AWS Australia and APAC hosted organizations
    - url: https://api.uk.aws.sigmacomputing.com
      description: Server for AWS UK hosted organizations
    - url: https://api.us.azure.sigmacomputing.com
      description: Server for Azure US hosted organizations
    - url: https://api.eu.azure.sigmacomputing.com
      description: Server for Azure Europe hosted organizations
    - url: https://api.ca.azure.sigmacomputing.com
      description: Server for Azure Canada hosted organizations
    - url: https://api.uk.azure.sigmacomputing.com
      description: Server for Azure United Kingdom hosted organizations
    - url: https://api.au.azure.sigmacomputing.com
      description: Server for Azure Australia hosted organizations
  /v2/dataModels/spec:
    post:
      operationId: createDataModelSpec
      summary: Create a data model from a code representation
      description: 'This endpoint creates a new data model in Sigma from a code representation. Use it to programmatically define and create data models that are then accessible from the Sigma UI.


        For more information on managing data models via the Sigma API, see [Manage data models as code](https://help.sigmacomputing.com/docs/manage-data-models-as-code). For more information on using this endpoint, including an end-to-end example, see [Create a data model from a code representation](https://help.sigmacomputing.com/docs/create-a-data-model-from-a-code-representation).


        ### Usage notes

        - To perform this operation, you must use API credentials owned by a user assigned an account type with **Create, edit, and publish data models** permission.

        - Retrieve a representation of an existing data model by calling the [/v2/dataModels/{dataModelId}/spec](https://help.sigmacomputing.com/reference/get-data-model-spec) endpoint.

        - To get a list of folders, call the [/v2/files](https://help.sigmacomputing.com/reference/list-files) endpoint and review the `id` field in the response for files with a `type` of `folder`.

        - The default format of the representation is JSON. To use YAML, add the header `Content-Type: application/yaml`.


        ### Usage scenarios

        - **Automation**: If you want to create several data models across one or more organizations, you can use this endpoint to programmatically create the data models.

        - **Integration**: Using this endpoint, you can create data models based on external data sources or integrate Sigma with other tools and platforms.

        - **Migration**: You can use this endpoint to migrate data models from one organization to another.

        - **Version control**: Developers can use this endpoint to programmatically manage, update, and version control data models between several organizations or tenants.

        - **Agentic workflows**: Agents can use these endpoints to directly manage data model contents in code.

        '
      tags:
      - dataModels
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataModels_createDataModelSpec_Response_200'
      requestBody:
        description: The request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataModelSpec'
    servers:
    - url: https://api.sigmacomputing.com
      description: Server for GCP (US) hosted organizations
    - url: https://api.sa.gcp.sigmacomputing.com
      description: Server for GCP (KSA) hosted organizations
    - url: https://aws-api.sigmacomputing.com
      description: Server for AWS US (West) hosted organizations
    - url: https://api.us-a.aws.sigmacomputing.com
      description: Server for AWS US (East) hosted organizations
    - url: https://api.ca.aws.sigmacomputing.com
      description: Server for AWS Canada hosted organizations
    - url: https://api.eu.aws.sigmacomputing.com
      description: Server for AWS Europe hosted organizations
    - url: https://api.au.aws.sigmacomputing.com
      description: Server for AWS Australia and APAC hosted organizations
    - url: https://api.uk.aws.sigmacomputing.com
      description: Server for AWS UK hosted organizations
    - url: https://api.us.azure.sigmacomputing.com
      description: Server for Azure US hosted organizations
    - url: https://api.eu.azure.sigmacomputing.com
      description: Server for Azure Europe hosted organizations
    - url: https://api.ca.azure.sigmacomputing.com
      description: Server for Azure Canada hosted organizations
    - url: https://api.uk.azure.sigmacomputing.com
      description: Server for Azure United Kingdom hosted organizations
    - url: https://api.au.azure.sigmacomputing.com
      description: Server for Azure Australia hosted organizations
  /v2/dataModels:
    get:
      summary: List data models
      description: "This endpoint retrieves a list of all data models available. You can use the response from this endpoint to review existing data models and determine if there are duplicates or gaps.\n\n### Usage notes\nThis endpoint requires no parameters for basic requests, but supports query parameters for pagination and response limit.\n\nUsers with the Admin account type can optionally retrieve all data models in the organization.\n\n#### Pagination\nThis endpoint supports pagination, which lets you retrieve large sets of data in manageable segments. The response includes pagination details as follows:\n- hasMore: A boolean value indicating whether there are more pages of data available beyond the current page.\n- total: The total number of entries available across all pages.\n- nextPage: An identifier or token that you can use in a subsequent request to retrieve the next page of data.\n\n#### Example response for pagination\n{\n  \"hasMore\": true,\n  \"total\": 104,\n  \"nextPage\": \"50\"\n}\nTo request additional pages, include the `nextPage` option in your followup request according to the endpoint's parameter requirements. This process can be repeated until the `nextPage` option returns `null`, indicating that no further data is available.\n\n### Usage scenarios\n- **Data model navigation:** Allows users to easily navigate through their available of data models and access the one they need.\n- **Track lineage**: Identify dependencies and lineage of data sources and data models.\n"
      parameters:
      - name: page
        schema:
          type: string
          description: Use to specify further pages using the string returned in the nextPage portion of the response.
          title: Page
        in: query
      - name: limit
        schema:
          type: number
          description: Number of results to return per page, with a maximum of 1,000 per request. Use the `page` option in subsequent requests to retrieve the next set of results.
          title: Limit
        in: query
      - name: excludeTags
        schema:
          type: boolean
          description: Whether to exclude additional information about tagged versions of each result
        in: query
      - name: skipPermissionCheck
        schema:
          type: boolean
          description: Only available to Sigma admins. Return all data models, regardless of whether the user has access.
        in: query
      operationId: listDataModels
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - entries
                  - nextPage
                  properties:
                    entries:
                      type: array
                      items:
                        allOf:
                        - type: object
                          required:
                          - dataModelId
                          properties:
                            dataModelId:
                              type: string
                              description: Unique identifier of the data model.
                              title: Data model ID
                        - type: object
                          required:
                          - dataModelUrlId
                          - name
                          - url
                          - path
                          - latestVersion
                          - ownerId
                          properties:
                            dataModelUrlId:
                              type: string
                            name:
                              type: string
                            url:
                              type: string
                            path:
                              type: string
                            latestVersion:
                              type: number
                            ownerId:
                              type: string
                        - type: object
                          required:
                          - createdBy
                          - updatedBy
                          - createdAt
                          - updatedAt
                          properties:
                            createdBy:
                              type: string
                              description: The identifier of the user who created this object.
                            updatedBy:
                              type: string
                              description: The identifier of the user or process that last updated this object.
                            createdAt:
                              type: string
                              format: date-time
                              description: When the object was created.
                            updatedAt:
                              type: string
                              format: date-time
                              description: When the object was last updated.
                        - type: object
                          properties:
                            isArchived:
                              type: boolean
                            tags:
                              type: array
                              items:
                                type: object
                                required:
                                - versionTagId
                                - tagName
                                - sourceVersion
                                - taggedAt
                                properties:
                                  versionTagId:
                                    type: string
                                    description: Unique identifier of the tag.
                                    title: Tag ID
                                  tagName:
                                    type: string
                                  sourceVersion:
                                    type: number
                                  taggedAt:
                                    type: string
                                    format: date-time
                      description: Array of results returned by the endpoint
                    nextPage:
                      type:
                      - string
                      - 'null'
                      description: Returns a string that can be used as the `page` parameter in the next request to fetch the next page of results. The last page of results returns `null`.
                - type: object
                  properties:
                    total:
                      type: number
                      description: Total number of results. Useful to determine if there is a need to paginate.
                    hasMore:
                      type: boolean
                      description: '**[Deprecated]** Indicates whether more results are available.'
        default:
          $ref: '#/components/responses/ApiError'
      externalDocs:
        url: ''
        description: 'Sigma API documentation:'
      tags:
      - dataModels
      security:
      - oauth2: []
    servers:
    - url: https://api.sigmacomputing.com
      description: Server for GCP (US) hosted organizations
    - url: https://api.sa.gcp.sigmacomputing.com
      description: Server for GCP (KSA) hosted organizations
    - url: https://aws-api.sigmacomputing.com
      description: Server for AWS US (West) hosted organizations
    - url: https://api.us-a.aws.sigmacomputing.com
      description: Server for AWS US (East) hosted organizations
    - url: https://api.ca.aws.sigmacomputing.com
      description: Server for AWS Canada hosted organizations
    - url: https://api.eu.aws.sigmacomputing.com
      description: Server for AWS Europe hosted organizations
    - url: https://api.au.aws.sigmacomputing.com
      description: Server for AWS Australia and APAC hosted organizations
    - url: https://api.uk.aws.sigmacomputing.com
      description: Server for AWS UK hosted organizations
    - url: https://api.us.azure.sigmacomputing.com
      description: Server for Azure US hosted organizations
    - url: https://api.eu.azure.sigmacomputing.com
      description: Server for Azure Europe hosted organizations
    - url: https://api.ca.azure.sigmacomputing.com
      description: Server for Azure Canada hosted organizations
    - url: https://api.uk.azure.sigmacomputing.com
      description: Server for Azure United Kingdom hosted organizations
    - url: https://api.au.azure.sigmacomputing.com
      description: Server for Azure Australia hosted organizations
  /v2/dataModels/{dataModelId}:
    get:
      summary: Get a data model
      description: "Get details of a specific data model by `dataModelId`.\n\n  ### Usage notes\n  - Retrieve the **dataModelId** by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint."
      parameters:
      - name: dataModelId
        schema:
          type: string
          description: Unique identifier of the data model.
          title: Data model ID
        in: path
        required: true
      - name: excludeTags
        schema:
          type: boolean
          description: Whether to exclude additional information about tagged versions of each result
        in: query
      operationId: getDataModel
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - dataModelId
                  properties:
                    dataModelId:
                      type: string
                      description: Unique identifier of the data model.
                      title: Data model ID
                - type: object
                  required:
                  - dataModelUrlId
                  - name
                  - url
                  - path
                  - latestVersion
                  - ownerId
                  properties:
                    dataModelUrlId:
                      type: string
                    name:
                      type: string
                    url:
                      type: string
                    path:
                      type: string
                    latestVersion:
                      type: number
                    ownerId:
                      type: string
                - type: object
                  required:
                  - createdBy
                  - updatedBy
                  - createdAt
                  - updatedAt
                  properties:
                    createdBy:
                      type: string
                      description: The identifier of the user who created this object.
                    updatedBy:
                      type: string
                      description: The identifier of the user or process that last updated this object.
                    createdAt:
                      type: string
                      format: date-time
                      description: When the object was created.
                    updatedAt:
                      type: string
                      format: date-time
                      description: When the object was last updated.
                - type: object
                  properties:
                    isArchived:
                      type: boolean
                    tags:
                      type: array
                      items:
                        type: object
                        required:
                        - versionTagId
                        - tagName
                        - sourceVersion
                        - taggedAt
                        properties:
                          versionTagId:
                            type: string
                            description: Unique identifier of the tag.
                            title: Tag ID
                          tagName:
                            type: string
                          sourceVersion:
                            type: number
                          taggedAt:
                            type: string
                            format: date-time
        default:
          $ref: '#/components/responses/ApiError'
      externalDocs:
        url: ''
        description: 'Sigma API documentation:'
      tags:
      - dataModels
      security:
      - oauth2: []
    servers:
    - url: https://api.sigmacomputing.com
      description: Server for GCP (US) hosted organizations
    - url: https://api.sa.gcp.sigmacomputing.com
      description: Server for GCP (KSA) hosted organizations
    - url: https://aws-api.sigmacomputing.com
      description: Server for AWS US (West) hosted organizations
    - url: https://api.us-a.aws.sigmacomputing.com
      description: Server for AWS US (East) hosted organizations
    - url: https://api.ca.aws.sigmacomputing.com
      description: Server for AWS Canada hosted organizations
    - url: https://api.eu.aws.sigmacomputing.com
      description: Server for AWS Europe hosted organizations
    - url: https://api.au.aws.sigmacomputing.com
      description: Server for AWS Australia and APAC hosted organizations
    - url: https://api.uk.aws.sigmacomputing.com
      description: Server for AWS UK hosted organizations
    - url: https://api.us.azure.sigmacomputing.com
      description: Server for Azure US hosted organizations
    - url: https://api.eu.azure.sigmacomputing.com
      description: Server for Azure Europe hosted organizations
    - url: https://api.ca.azure.sigmacomputing.com
      description: Server for Azure Canada hosted organizations
    - url: https://api.uk.azure.sigmacomputing.com
      description: Server for Azure United Kingdom hosted organizations
    - url: https://api.au.azure.sigmacomputing.com
      description: Server for Azure Australia hosted organizations
  /v2/dataModels/{dataModelId}:materialize:
    post:
      summary: Run a scheduled materialization for a data model element
      description: "This endpoint runs a scheduled materialization for an element in a data model. Materialization processes the data of the specified element, allowing the data to be stored or cached for optimized access and performance.\n\n  For more details on materialization, see [Materialization](https://help.sigmacomputing.com/docs/materialization).\n\n  ### Usage notes\n  - The materialization schedule for the specified element must be created beforehand.\n  - Retrieve the **sheetId** by calling the [/v2/dataModels/{dataModelId}/materialization-schedules](https://help.sigmacomputing.com/reference/list-data-model-materialization-schedules) endpoint.\n  - Retrieve the **dataModelId** by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint.\n\n  ### Usage scenarios\n  - **Performance optimization:** Use this endpoint to improve response times for frequently accessed data model elements.\n  - **Data refresh:** Allows users to manually (programmatically) refresh the data of specific data model elements to ensure that the latest data is available for analysis and reporting.\n\n  ### Best practices\n  - Prioritize materialization for elements that are heavily used or form critical components of business reports.\n  - Monitor the performance impacts of materialization and adjust strategies as necessary to optimize resource usage and response times."
      parameters:
      - name: dataModelId
        schema:
          type: string
          description: Unique identifier of the data model.
          title: Data model ID
        in: path
        required: true
      operationId: materializeDataModelElement
      requestBody:
        description: The request body.
        content:
          application/json:
            schema:
              type: object
              required:
              - sheetId
              properties:
                sheetId:
                  type: string
                  description: Identifier for the materialization schedule of this element.
                  title: Sheet ID
      responses:
        '200':
          description: The response body.
          content:
            application/json:
              schema:
                type: object
                required:
                - materializationId
                properties:
                  materializationId:
                    type: string
        default:
          $ref: '#/components/responses/ApiError'
      externalDocs:
        url: ''
        description: 'Sigma API documentation:'
      tags:
      - dataModels
      security:
      - oauth2: []
    servers:
    - url: https://api.sigmacomputing.com
      description: Server for GCP (US) hosted organizations
    - url: https://api.sa.gcp.sigmacomputing.com
      description: Server for GCP (KSA) hosted organizations
    - url: https://aws-api.sigmacomputing.com
      description: Server for AWS US (West) hosted organizations
    - url: https://api.us-a.aws.sigmacomputing.com
      description: Server for AWS US (East) hosted organizations
    - url: https://api.ca.aws.sigmacomputing.com
      description: Server for AWS Canada hosted organizations
    - url: https://api.eu.aws.sigmacomputing.com
      description: Server for AWS Europe hosted organizations
    - url: https://api.au.aws.sigmacomputing.com
      description: Server for AWS Australia and APAC hosted organizations
    - url: https://api.uk.aws.sigmacomputing.com
      description: Server for AWS UK hosted organizations
    - url: https://api.us.azure.sigmacomputing.com
      description: Server for Azure US hosted organizations
    - url: https://api.eu.azure.sigmacomputing.com
      description: Server for Azure Europe hosted organizations
    - url: https://api.ca.azure.sigmacomputing.com
      description: Server for Azure Canada hosted organizations
    - url: https://api.uk.azure.sigmacomputing.com
      description: Server for Azure United Kingdom hosted organizations
    - url: https://api.au.azure.sigmacomputing.com
      description: Server for Azure Australia hosted organizations
  /v2/dataModels/{dataModelId}/col

# --- truncated at 32 KB (1368 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sigma-computing/refs/heads/main/openapi/sigma-computing-datamodels-api-openapi.yml