Tag API
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.
GET v2/tags
Returns a list of tags.
POST v2/workbooks/tag
Tags a workbook using the Workbook ID.
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
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.
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
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
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