Workbook API

The following article covers Sigma’s developer API for workbooks.Workbook exporting is covered in Workbook Export API. Workbook schemas are covered in Workbook Schema API.

We frequently add new endpoints workbooks, see Workbooks  for a complete list.

Summary of Content

Endpoints
The Workbook Object
      Attributes
The Workbook List Object
      Attributes
List Workbooks
      Permissions 
      Parameters
      cURL Request
      Response
Look up a Workbook
      Permissions
      Parameters
      cURL Request
      Response
      Example
List Workbooks Controls
     Permissions
     Parameters
     cURL Request
     Response
List pages in a workbook
List embeds for a workbook
List elements in a workbook page
Related Resources

Endpoints

GET /v2/workbooks

      Returns a list of available workbooks.
      Try it in Swagger

GET /v2/workbooks/{workbookId}

      Returns a workbook object based on a unique workbook identifier, workbookId.

      Try it in Swagger

GET /v2/workbooks/{workbookId}/pages

      Returns the list of pages in a workbook.

      Try it in Swagger

GET /v2/workbooks/{workbookId}/controls

      Returns the list of controls in a workbook.
      Try it in Swagger

GET /v2/workbooks/{workbookId}/embeds

      Returns a list of available embeds for a specific workbook.
      Try it in Swagger

GET /v2/workbooks/{workbookId}/pages/{pageId}/elements

      Returns the list of elements in a workbook page.

      Try it in Swagger

The Workbook Object

Attributes

workbookId string

The workbook’s unique identifier.

workbookUrlId string

The workbook’s unique identifier as shown in the workbook's URL.

 

createdBy string

The unique identifier, memberId, of the organization member who created the workbook.

updatedBy string

The unique identifier, memberId, of the organization member who last modified changes to the workbook.

createdAt string

The timestamp at which the workbook was created.

updatedAt string

The timestamp at which the workbook was last modified.

name string

The workbook name.

url string

The URL path to the workbook.

path string

The Sigma file system path to the workbook.

 

latestVersion number

The version number of the workbook. 

 

tags array

Array containing "versionTagId" and "name" for Version Tags.

 

IsArchived boolean | undefined

True if the workbook has been archived.

 

{
   "workbookId": string,
   "workbookUrlId": string,
   "createdBy": string,
   "updatedBy": string,
   "createdAt": string,
   "updatedAt": string,
   "name": string,
   "url": string,
   "path": string,
   "latestVersion": number,
   "isArchived": boolean,
   "tags": array
}

 

The Workbook List Object

Attributes

entries Array<Workbook>

A list of workbooks matching the requested parameters.

Default number of entries per page: 50

 

hasMore boolean

True if additional workbooks are available (accessible but not included in the current list).

 

total number

That total number of available workbooks, including those on other pages.

Workbooks in the organization that are not accessible by the user are excluded from this count.

Note: If your organization has over 10,000 workbooks, the total displayed here never exceeds 10,000. The additional workbooks are active and available. 

 

nextPage string | null

The next page in the list of workbooks. Used for pagination.

{
   "entries": [
     <Workbook>,
     <Workbook>,
     ...
  ],
  "hasMore": boolean,
  "total": number,
  "nextPage": string
}

 

List Workbooks

Returns a list of available workbooks.

GET /v2/workbooks

Try it in Swagger

Permissions 

• You will only  have access to the workbooks available in Sigma to the user account associated with the API access token.
  Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
  
  

Parameters

page string [optional]

An identifier used for pagination. 

limit number [optional]

The number of workbooks to be returned. 

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks?page={page}&limit={limit} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Response

Returns Array<Workbook>.

{
 "entries": [
     <Workbook>,
     <Workbook>,
     ...
  ],
  "hasMore": boolean,
  "total": number,
    "nextPage": string | null
  }

 

Example

Example Request:

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Example Response:

{
  "entries": [
    {
      "workbookId": "dbaf643d-cba5-40c0-b0f5-6bc529659ab5",
      "workbookUrlId": "3isLx3RUNrtTZMnoAWv8ns",
      "createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
      "updatedBy": "8C2szXPJqLXpIezcD5adESnwfPUpp",
      "createdAt": "2021-10-04T20:36:40.960Z",
      "updatedAt": "2021-10-11T18:38:16.978Z",
      "name": "Plugs Electronics Sales Performance",
      "url": "https://app.sigmacomputing.com/my-org/b/6Rrtndc3aWx7T30cWvLEAW",
      "path": "Sales Workspace/Sales Performance",
      "latestVersion": 2,
      "isArchived": false,
      "tags": [
               {
                "versionTagId": "a621701c-fb21-4cb3-a5f9-2aaa730f181b",
                "name": "Production"
                }
               ]
    },
    {
      "workbookId": "9551t76d-23f7-4195-ad98-d9d2578c7d05",
      "workbookUrlId": "1VtbkbnVZzqHUvHvtUKrHI",
      "createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
      "updatedBy": "6VZpXc5Pl6XpIezcD5adtYi23Pt1u",
      "createdAt": "2021-10-04T21:14:25.963Z",
      "updatedAt": "2021-10-07T21:01:40.848Z",
      "name": "Sales by Product Group",
      "url": "https://app.sigmacomputing.com/my-org/b/4xLe1KDR78M9cmYkgYJrtX",
      "path": "Sales Workspace/Sales Performance",
      "latestVersion": 1,
      "isArchived": true
    },
    ...
  ],
  "hasMore": false,
  "total": 2,
  "nextPage": null
}

 

Look up a Workbook

Returns a workbook object based on a unique identifier, workbookId.

GET /v2/workbooks/{workbookId}

Try it in Swagger

 

Permissions 

• You will only have access to the workbooks available in Sigma to the user account associated with the API access token.
  Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
  
  

Parameters

None 

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Response

Returns a workbook object.

{
   "workbookId": string,
   "workbookUrlId": string,
   "createdBy": string,
   "updatedBy": string,
   "createdAt": string,
   "updatedAt": string,
   "name": string,
   "url": string,
   "path": string,
   "latestVersion": number,
   "isArchived": boolean,
   "tags": array
}

 

Example

Example Request:

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/dbaf643d-cba5-40c0-b0f5-6bc529659ab5' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

 

Example Response:

{
   "workbookId": "dbaf643d-cba5-40c0-b0f5-6bc529659ab5",
   "workbookUrlId": "3isLx3RUNrtTZMnoAWv8ns",
   "createdBy": "8C2szXPJqLXpIevcD5adESnwfPUpp",
   "updatedBy": "8C2szXPJqLXpIezcD5adESnwfPUpp",
   "createdAt": "2021-10-04T20:36:40.960Z",
   "updatedAt": "2021-10-11T18:38:16.978Z",
   "name": "Plugs Electronics Sales Performance",
   "url": "https://app.sigmacomputing.com/my-org/b/6Rrtndc3aWx7T30cWvLEAW",
   "path": "Sales Workspace/Sales Performance",
  "latestVersion": 2,
  "isArchived": false,
  "tags": [
           {
            "versionTagId": "a621701c-fb21-4cb3-a5f9-2aaa730f181b",
            "name": "Production"
            }
          ]
}

List pages in a workbook

Returns a list of available embeds for a specific workbook.

GET /v2/workbooks/{workbookId}/pages

Permissions

• You will only  have access to the workbooks available in Sigma to the user account associated with the API access token.

Path Parameters

workbookId string [required]

The workbook’s unique identifier.

Query Parameters

page string [optional]

An identifier used for pagination. 

limit number [optional]

The number of workbooks to be returned. 

tag string [optional]

The name of a tag, if applied. Different tagged versions can have different pages.

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/pages \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{
  "entries": [
    {
      "pageId": "string",
      "name": "string",
      "hidden": false
    }
  ],
  "nextPage": "string",
  "total": 0
}

List Workbook Controls

Returns the list of controls in a workbook.

GET /v2/workbooks/{workbookId}/controls

Permissions 

• You will only  have access to the workbooks available in Sigma to the user account associated with the API access token.

Path Parameters

workbookId string [required]

The workbook’s unique identifier.

 

Query Parameters

page string [optional]

An identifier used for pagination. 

limit number [optional]

The number of workbooks to be returned. 

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/controls \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{
  "entries": [
    {
      "name": "string",
      "valueType": "string"
    }
  ],
  "nextPage": "string",
  "total": 0
}

List Embeds for a workbook

Returns a list of available embeds for a specific workbook.

GET /v2/workbooks/{workbookId}/embeds

Permissions

• You will only  have access to the workbooks available in Sigma to the user account associated with the API access token.

Path Parameters

workbookId string [required]

The workbook’s unique identifier.

Query Parameters

page string [optional]

An identifier used for pagination. 

limit number [optional]

The number of workbooks to be returned. 

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/embeds \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{
  "entries": [
    {
      "embedId": "string",
      "embedUrl": "string",
      "public": false
    }
  ],
  "nextPage": "string",
  "total": 0,
  "hasMore": false
}

 

Return elements in a workbook page

Returns the list of elements in a workbook page.

GET /v2/workbooks/{workbookId}/pages/{pageId}/elements

Permissions

• You will only  have access to the workbooks available in Sigma to the user account associated with the API access token.

Path Parameters

workbookId string [required]

The workbook’s unique identifier.

 

pageId string [required]

The page's unique identifier.

 

Query Parameters

page string [optional]

An identifier used for pagination. 

limit number [optional]

The number of workbooks to be returned. 

cURL Request

curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/pages/{pageId}/elements \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \

Response

{
  "entries": [
    {
      "elementId": "string",
      "name": "string",
      "type": "string",
      "columns": ["string"],
      "vizualizationType": "string",
      "error": "string"
    }
  ],
  "nextPage": "string",
  "total": 0
}

Related Resources

API Documentation

Get Started with Sigma's API
Create an API Token and Client ID
Identify Unique Ids in Sigma

Product Documentation

Workbooks overview