Labels API Code Samples

Selection of code samples that demonstrate the use of the Labels API. Copy and edit these code samples to suit your needs.

When using the code samples, remember to replace:

  • {vanity_name} with your tenant name
  • {api_key} with your API key
  • {security_token} with a valid security token

These code samples may not include all available parameters and request body fields for each endpoint. For the endpoint's full request schema, see "Labels" in API Reference.

Retrieve all labels and assignments

Use this sample request to retrieve a list of all labels and assignments.

Copy
cURL sample request: Retrieve a list of all labels and assignments
curl -X GET --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns a list of labels including the label ID, display name, and color, and a list of label assignments containing the label ID and corresponding content ID.

Copy 
{
  "labels": [
    {
      "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
      "displayName": "Costs",
      "color": "#f91515"
    },
    {
      "labelId": "e3220bf4-4dbf-41a4-93bf-1cbdecd0bedf",
      "displayName": "DEI",
      "color": "#b6d5fb"
    }
  ],
  "assignments": [
    {
      "labelId": "e3220bf4-4dbf-41a4-93bf-1cbdecd0bedf",
      "contentId": "75ffd7d4-b643-40fe-88a2-ea6b33c2fbf9"
    },
    {
      "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
      "contentId": "f1cbfd3d-0c17-461c-ab01-771a1d608fed"
    },
    {
      "labelId": "e3220bf4-4dbf-41a4-93bf-1cbdecd0bedf",
      "contentId": "f1cbfd3d-0c17-461c-ab01-771a1d608fed"
    }
  ]
}

Create a label

Use this sample request to create a label with a display name and color, and automatically assign the label to an analysis or report.

Copy
cURL sample request: Create a label
curl -X POST --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "displayName": "Costs",
    "color": "#f91515",
    "contentId": "f1cbfd3d-0c17-461c-ab01-771a1d608fed"
}'

The response returns the created label's information such as label ID, display name, and color, and the label assignment containing the label ID and corresponding content ID.

Copy 
{
  "createdLabel": {
    "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
    "displayName": "Costs",
    "color": "#f91515"
  },
  "labelAssignment": {
    "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
    "contentId": "f1cbfd3d-0c17-461c-ab01-771a1d608fed"
  }
}

Update a label

Use this sample request to update a label with a new display name and color. If values are omitted, the request will fail.

Copy
cURL sample request: Update a label
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}' \
-H 'Content-Type: application/json' \
-d '{
    "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
    "displayName": "Costs 2027",
    "color": "#ffffff"
}'

The response returns the updated label's information such as label ID, display name, and color.

Copy 
{
    "labelId": "9e9a007c-e802-4ecb-b2f5-f1ba9e36d870",
    "displayName": "Costs 2027",
    "color": "#ffffff"
}

Delete a label

Use this sample request to delete a label. To retrieve label IDs, see GET/v1/analysis-labels/labels.

Copy
cURL sample request: Delete a label
curl -X DELETE --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels/9e9a007c-e802-4ecb-b2f5-f1ba9e36d870' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns 200 OK.

Assign a label

Use this sample request to assign a label to an analysis or report. You must specify the label ID and content ID.

  • To retrieve label IDs, see GET/v1/analysis-labels/labels.

  • To retrieve content IDs, do the following:

    • Reports: see GET /v1alpha/reporting/reports.

    • Analyses: Retrieve ID by opening an analysis in the production version of a tenant and copying the string after the last forward slash (/) in the URL. For example: https://jupiter.visier.com/hr/prod/appcontainer?previewId=VnTY9W1EnhLQYrkRnJMpTQ..&previewType=Production#/analytics/myanalyses/f1cbfd3d-0c17-461c-ab01-771a1d608fed. The analysis ID is f1cbfd3d-0c17-461c-ab01-771a1d608fed. Alternatively, retrieve the ID by copying the Analysis ID or contentId generated when embedding a visualization. For more information, see Embed a Visualization.

Copy
cURL sample request: Assign a label
curl -X PUT --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels/9e9a007c-e802-4ecb-b2f5-f1ba9e36d870/contents/f1cbfd3d-0c17-461c-ab01-771a1d608fed' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns 200 OK.

Unassign a label

Use this sample request to unassign a label from an analysis or report. You must specify the label ID and content ID.

  • To retrieve label IDs, see GET/v1/analysis-labels/labels.

  • To retrieve content IDs, do the following:

    • Reports: see GET /v1alpha/reporting/reports.

    • Analyses: Retrieve ID by opening an analysis in the production version of a tenant and copying the string after the last forward slash (/) in the URL. For example: https://jupiter.visier.com/hr/prod/appcontainer?previewId=VnTY9W1EnhLQYrkRnJMpTQ..&previewType=Production#/analytics/myanalyses/f1cbfd3d-0c17-461c-ab01-771a1d608fed. The analysis ID is f1cbfd3d-0c17-461c-ab01-771a1d608fed. Alternatively, retrieve the ID by copying the Analysis ID or contentId generated when embedding a visualization. For more information, see Embed a Visualization.

Copy
cURL sample request: Unassign a label
curl -X DELETE --url 'https://{vanity_name}.api.visier.io/v1/analysis-labels/labels/9e9a007c-e802-4ecb-b2f5-f1ba9e36d870/contents/f1cbfd3d-0c17-461c-ab01-771a1d608fed' \
-H 'apikey:{api_key}' \
-H 'Cookie:VisierASIDToken={security_token}'

The response returns 200 OK.