ThoughtSpot generates shareable links for Liveboards, Answers, visualizations, SpotIQ insights, Spotter conversations, and other objects. These links appear in scheduled emails, the Share dialog, and alert notifications.
By default, shareable links point to your ThoughtSpot instance. If you embed ThoughtSpot in your own application, you can use the link customization REST API v2 endpoints to redirect these links to your application. When a user clicks a shared link, they are directed to your embedding application instead of the ThoughtSpot application.
Each link type has a URL template with placeholders that ThoughtSpot replaces with the object details when it generates a link. To customize the links:
Retrieve the current URL templates
Call POST /api/rest/2.0/customization/links/search to view the templates in effect at the cluster level or for your Org.
Update the URL templates
Call POST /api/rest/2.0/customization/links/update with the REPLACE operation to set a template, or with the RESET operation to clear an override.
You can manage the templates at the following scopes:
CLUSTER: Sets the default templates that all Orgs inherit.
ORG: Sets the templates for the caller’s Org and overrides the default settings. Requires Orgs to be enabled on your instance.
Cluster-level templates are available only to callers in the primary Org. If an Org does not set its own template for a link type, it inherits the cluster template. If the cluster does not set one either, ThoughtSpot uses its default template.
To use the Link Customization APIs, the user requires one of the following privileges:
ADMINISTRATION (Can administer ThoughtSpot)
DEVELOPER (Has developer privilege)
Authenticate API requests with a bearer token. For information about obtaining a token, see REST API v2 authentication.
The /api/rest/2.0/customization/links/search API endpoint retrieves the URL templates that ThoughtSpot uses to generate shareable links, at the cluster level or for the Org that the caller is signed in to. Use this endpoint to verify what an Org has customized before you modify it, or to confirm the destination URLs used in scheduled emails and the Share dialog.
Cluster-level templates are the default that Orgs inherit. Org-level templates override that default.
| Parameter | Description |
|---|---|
| String. Optional. The scope to retrieve:
If you omit the parameter, the API returns whichever of these scopes the caller can access. |
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/search' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{}'If the API request is successful, the API returns an array of link preferences, one for each scope.
[
{
"scope": "CLUSTER",
"org": null,
"templates": [
{
"type": "LIVEBOARD_SHARE_URL",
"value": "https://mysite.com/#/pinboard/{object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "VISUALIZATION_SHARE_URL",
"value": "https://mysite.com/#/pinboard/{object-id}/{sub-object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "ANSWER_SHARE_URL",
"value": "https://mysite.com/#/saved-answer/{object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "SPOTIQ_ANALYSIS_URL",
"value": "https://mysite.com/#/insight/{object-id}",
"is_overridden": true
},
{
"type": "UNSUBSCRIBE_URL",
"value": "https://mysite.com/#/user-preference",
"is_overridden": true
},
{
"type": "GENERIC_URL",
"value": "https://mysite.com/#/{path}",
"is_overridden": true
},
{
"type": "CONVERSATION_SHARE_URL",
"value": "https://{ThoughtSpot-Host}/#/insights/conv-assist/s/{conversation-id}?{ts-query-params}",
"is_overridden": false
}
]
},
{
"scope": "ORG",
"org": {
"id": 12345,
"name": "Org1"
},
"templates": [
{
"type": "LIVEBOARD_SHARE_URL",
"value": "https://org1-mysite.com/#/pinboard/{object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "VISUALIZATION_SHARE_URL",
"value": "https://org1-mysite.com/#/pinboard/{object-id}/{sub-object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "ANSWER_SHARE_URL",
"value": "https://org1-mysite.com/#/saved-answer/{object-id}?{ts-query-params}",
"is_overridden": true
},
{
"type": "SPOTIQ_ANALYSIS_URL",
"value": "https://org1-mysite.com/#/insight/{object-id}",
"is_overridden": true
},
{
"type": "UNSUBSCRIBE_URL",
"value": "https://org1-mysite.com/#/user-preference",
"is_overridden": true
},
{
"type": "GENERIC_URL",
"value": "https://org1-mysite.com/#/{path}",
"is_overridden": true
},
{
"type": "CONVERSATION_SHARE_URL",
"value": "https://org1-mysite.com/#/insights/conv-assist/s/{conversation-id}?{ts-query-params}",
"is_overridden": true
}
]
}
]| Parameter | Description |
|---|---|
| Indicates whether the link customization changes are applied globally ( |
| The Org that the link templates belong to. Includes the |
| The effective URL template for every link type at this scope. Each entry includes the following attributes:
|
The /api/rest/2.0/customization/links/update API endpoint updates the URL templates that ThoughtSpot uses to generate shareable links, at the cluster level or for the Org that the caller is signed in to. Use this endpoint to point shared links to your embedding application, so that a link in a scheduled email or the Share dialog opens your page instead of the ThoughtSpot application.
| Parameter | Description |
|---|---|
| String. Optional. The scope to apply the templates at:
|
| String. Optional. The operation to perform:
|
| Array of objects. The link types to update. At least one entry is required. For each entry, specify the following attributes:
|
This is a partial update. Only the link types listed in templates change. All other link types keep their current value, whether it is set at this scope or inherited.
The API rejects a template that doesn’t include the placeholders required for its link type. For more information, see Supported link types and placeholders.
The API rejects a request that includes the same link type more than once.
The API rejects a request that includes a value with the RESET operation.
To clear every override, list all link types with the RESET operation.
Resetting at the cluster level changes only the cluster default. An Org that has set its own value keeps it.
Each link type requires specific placeholders in its URL template. ThoughtSpot rejects a template that does not include the required placeholders.
| Link type | Used for | Required placeholders | Example template |
|---|---|---|---|
| Links to a Liveboard in share and scheduled job notifications. |
|
|
| Links to a visualization on a Liveboard. |
|
|
| Links to a saved Answer in share notifications. |
|
|
| Links to a SpotIQ analysis. |
|
|
| The Unsubscribe link in notification emails. | None |
|
| Navigation links and pages that the other link types don’t cover. |
|
|
| Links to a shared Spotter conversation. |
|
|
The placeholders are replaced as follows:
{object-id}: The GUID of the Liveboard, Answer, or SpotIQ analysis.
{sub-object-id}: The GUID of the visualization.
{conversation-id}: The ID of the shared Spotter conversation.
/vercel/path0/modules/ROOT/pages/partials: The ThoughtSpot application page path.
{ts-query-params}: The query parameters that ThoughtSpot passes in the link, for example, the parameters required to unsubscribe from an alert.
{ts-query-params} is optional for any link type that does not require it. ThoughtSpot substitutes it wherever it appears and removes it when there is nothing to substitute, so it never appears in a generated link.
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"scope": "ORG",
"operation": "REPLACE",
"templates": [
{
"type": "LIVEBOARD_SHARE_URL",
"value": "https://www.mysite.com/dashboards/{object-id}?{ts-query-params}"
}
]
}'curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"scope": "ORG",
"operation": "RESET",
"templates": [
{
"type": "LIVEBOARD_SHARE_URL"
}
]
}'If the API request is successful, the API returns 204 No Content without a response body.
| HTTP status code | Description |
|---|---|
204 | Link preferences updated successfully. |
400 | Invalid request. For example, a template is missing a required placeholder, a link type is repeated, or a |
401 | Authentication token is missing, expired, or invalid. |
403 | The caller does not have the required privilege. |
500 | Unexpected server error. |