Use these endpoints to  create a tag, return a list of tags, and to tag a version of a workbook which allows you directly reference the tagged versions. A primary use case for these endpoints is to build a workbook and migrate that workbook from development to higher environments.

Summary of Content

Endpoints
The Tag Object
Create a Tag
List Tags
Tag a Workbook
Related Resources


Endpoints

POST v2/tags

Creates a new tag. Learn more

GET v2/tags

Returns a list of tags. Learn more.  

POST v2/workbooks/tag

Tags a workbook using the Workbook ID. Learn more


The Tag Object

Attributes

versionTagId | string

ID of the version tag in the table.

taggedWorkbookId | string

Unique identifier of the tagged workbook.

taggedWorkbookVersion | number

Value that identifies specific version of the workbook. 

ownerId | string

The memberID of the doc owner. 

name | string

The name you assigned to a tag.

createdBy | string

The ID of the member who created the tag. 

updatedBy | string

The ID of the member who updated the tag. 

createdAt | string

Date and time tag was created.

updatedAt | string

Date and time tag was updated.

isArchived | boolean

Is the tag archived: true or false. This functionality is coming soon.


Create a Tag

Creates a new tag.

POST v2/tags

Try it on swagger

Permissions

  • You must be an admin to use this endpoint. 

Request Parameters

name| string [Required]

Create a name for the string. 

color| string [Required]

Select a color for your tag by entering the name of the color. 

The following colors are supported:

  • cyan
  • lime
  • violet
  • plum
  • yellow
  • bronze

In the example below, the tags were created with lime and plum colors.

company apps

 

cURL Request

curl --location --request \'POST' \'https://api.sigmacomputing.com/v2/tags' \ 
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{  
     "name":  "tagname", 
     "color": "cyan" 
}'

 

Response

{
"name": "tagname",
  "versionTagId": "dada3122-5914-4e4f-20r603d7e921"
}

List Tags

Returns a list of tags. 

GET v2/tags

Try it on Swagger.

Permissions

  • You must be an admin to use this endpoint. 

Query Parameters

page | string [optional]

An identifier used for pagination. 

limit | number [optional]

The number of workbooks to be returned. 

searchstring | string [optional]

A value you want to return. 

 

cURL Request

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

 

Response

{
  "entries": [
    {
      "versionTagId": "string",
      "name": "string",
      "ownerId": "string",
      "createdBy": "string",
      "updatedBy": "string",
      "createdAt": "2022-12-16T02:27:55.952Z",
      "updatedAt": "2022-12-16T02:27:55.952Z",
      "isArchived": true
}
],
"hasmore": true,
"nextpage": "string",
"total": 0
}

Tag a Workbook

This endpoint allows you to tag a workbook. 

POST v2/workbooks/tag

Try it on swagger

Permissions

  • You must be an admin to use this endpoint. 

Request Parameters

workbookId | string [required]

The workbook’s unique identifier.
Use the Workbook API to locate the workbookId. The workbookId is also included in the URL of a workbook.  

GET /v2/workbooks


workbookVersion
| number [required]

The number of the workbook version. 

tag | string [required]

The name of the tag.

sourceMappingConfig | array <Connection> [optional]

Use this array to change the original data source for a workbook. The available fields are defined below.  {fromConnectionId, toConnectionId, path}

fromConnectionId | string

Use the Connection API to locate the connection ID. This is the workbook's origin connection. 

GET /v2/connections?limit=<number>&page=<page-string>


toConnectionId
| string

Use the Connection API to locate the connection ID that you want to migrate the workbook to. 

GET /v2/connections?limit=<number>&page=<page-string>

 

paths | array <Path> [optional]

An array within sourceMappingConfig array that defines the origin and destination paths. {fromPath, toPath}


fromPath | string

Use the Connection API to locate the origin path ID for the workbook.

GET /v2/connections?limit=<number>&page=<page-string>


toPath | string

Use the Connection API to locate the path ID that you want to migrate the workbook to.

GET /v2/connections?limit=<number>&page=<page-string>

 

sourceVersions | number [optional]

An object that maps a dataset ID to a dataset version. The dataset ID is included in the URL of a dataset.

 

cURL Request

curl --location --request POST 'https://api.sigmacomputing.com/v2/workbooks/tag' \ 
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"workbookId": "string",
"workbookVersion": number,
"tag": "staging",
"sourceMappingConfig": array [
{
"fromConnectionId": string,
"toConnectionId": string,
"paths": array,
"fromPath": string,
"toPath": string,
}
],
"sourceVersions": number
}'

 

Response

{
"versionTagId": string,
"taggedWorkbookId": string,
"taggedWorkbookVersion": number
}

Example

Example Request:

In the example below, the POST request tags version 3 of the workbook as staging.

curl --location --request POST 'https://api.sigmacomputing.com/v2/workbooks/tag' \ 
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"workbookId": "rNfpYbVbQM9oIU6g284RE",
"workbookVersion": 3,
"tag": "staging",
"sourceMappingConfig": [
{
"fromConnectionId": "dada5142-5914-4e4f-9328-20e603b7e910",
"toConnectionId": "dada3122-5914-4e9f-9428-20e623d7e920",
"paths": [{ "fromPath": ["SNOWFLAKE_SAMPLE_DATA", "WEATHER", "DAILY_14_TOTAL"],
"toPath": ["SNOWFLAKE_SAMPLE_DATA", "WEATHER", "DAILY_16_TOTAL"]}]
}
],
"sourceVersions": {4}
}'

 

Example Response:

{
"versionTagId": "dada3122-5914-4e4f-20r603d7e921",
"taggedWorkbookId": "dada3112-5914-4e4f-9428-20w603d7e990",
"taggedWorkbookVersion": 3
}

Related Resources

Connection API
Get an API Token and Client ID
Version Tagging

 


Was this page helpful?
Yes No