# Link Customization APIs

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/link-customization-api

# Link Customization APIs

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.

## Link customization workflow

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:

1.  [Retrieve the current URL templates](#search-link-customizations)  
    Call `POST /api/rest/2.0/customization/links/search` to view the templates in effect at the cluster level or for your Org.
    
2.  [Update the URL templates](#update-link-customizations)  
    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.
    

### Scopes

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.

### Required privileges

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]({{navprefix}}/{{authentication}}).

## Searching link customizations

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.

### Request parameters

 
| Parameter | Description |
| --- | --- |
| 
`scope`

 | 

_String_. Optional. The scope to retrieve:

-   `CLUSTER` returns the cluster templates. Available only to callers in the primary Org.
    
-   `ORG` returns the templates for the Org that the caller is signed in to. Requires Orgs to be enabled.
    

If you omit the parameter, the API returns whichever of these scopes the caller can access.





 |

### Example request

```cURL
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 '{}'
```

### Example response

If the API request is successful, the API returns an array of link preferences, one for each scope.

```JSON
[
  {
    "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
      }
    ]
  }
]
```

### Response parameters

 
| Parameter | Description |
| --- | --- |
| 
`scope`

 | 

Indicates whether the link customization changes are applied globally (`CLUSTER`) or for an individual Org (`ORG`).

 |
| 

`org`

 | 

The Org that the link templates belong to. Includes the `id` and `name` of the Org. The value is `null` when `scope` is `CLUSTER`.

 |
| 

`templates`

 | 

The effective URL template for every link type at this scope. Each entry includes the following attributes:

-   `type`: The link type. For the list of supported types, see [Supported link types and placeholders](#link-types).
    
-   `value`: The effective URL template at the requested scope.
    
-   `is_overridden`: `true` when the scope stores a value that differs from the value it would otherwise inherit. For `ORG`, the inherited value is the cluster template. For `CLUSTER`, it is the ThoughtSpot default. The value is `false` when they match.
    





 |

## Updating link customizations

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.

### Request parameters

 
| Parameter | Description |
| --- | --- |
| 
`scope`

 | 

_String_. Optional. The scope to apply the templates at:

-   `ORG` (default) updates the templates for the Org that the caller is signed in to. Requires Orgs to be enabled.
    
-   `CLUSTER` updates the defaults that all Orgs inherit. Available only to callers in the primary Org.
    





 |
| 

`operation`

 | 

_String_. Optional. The operation to perform:

-   `REPLACE` (default) sets each listed link type to the `value` provided in the request.
    
-   `RESET` clears each listed link type, so an Org falls back to the cluster template and the cluster falls back to the ThoughtSpot default.
    





 |
| 

`templates`

 | 

_Array of objects_. The link types to update. At least one entry is required. For each entry, specify the following attributes:

-   `type`. _String_. The link type. For the list of supported types, see [Supported link types and placeholders](#link-types).
    
-   `value`. _String_. The URL template, including the placeholders that the link type requires. Required for `REPLACE`. Do not specify it for `RESET`.
    





 |

### Update behavior

-   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](#link-types).
    
-   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.
    

### Supported link types and placeholders

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 |
| --- | --- | --- | --- |
| 
`LIVEBOARD_SHARE_URL`

 | 

Links to a Liveboard in share and scheduled job notifications.

 | 

`{object-id}`, `{ts-query-params}`

 | 

`https://www.mysite.com/dashboards/{object-id}?{ts-query-params}`

 |
| 

`VISUALIZATION_SHARE_URL`

 | 

Links to a visualization on a Liveboard.

 | 

`{object-id}`, `{sub-object-id}`, `{ts-query-params}`

 | 

`https://www.mysite.com/dashboards/{object-id}/charts/{sub-object-id}?{ts-query-params}`

 |
| 

`ANSWER_SHARE_URL`

 | 

Links to a saved Answer in share notifications.

 | 

`{object-id}`, `{ts-query-params}`

 | 

`https://www.mysite.com/answers/{object-id}?{ts-query-params}`

 |
| 

`SPOTIQ_ANALYSIS_URL`

 | 

Links to a SpotIQ analysis.

 | 

`{object-id}`

 | 

`https://www.mysite.com/insights/{object-id}`

 |
| 

`UNSUBSCRIBE_URL`

 | 

The **Unsubscribe** link in notification emails.

 | 

None

 | 

`https://www.mysite.com/account/email-preferences`

 |
| 

`GENERIC_URL`

 | 

Navigation links and pages that the other link types don’t cover.

 | 

`/vercel/path0/modules/ROOT/pages/partials`

 | 

`https://www.mysite.com//vercel/path0/modules/ROOT/pages/partials`

 |
| 

`CONVERSATION_SHARE_URL`

 | 

Links to a shared Spotter conversation.

 | 

`{conversation-id}`, `{ts-query-params}`

 | 

`https://www.mysite.com/spotter/{conversation-id}?{ts-query-params}`

 |

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.

### Example request

Replace a template

```cURL
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}"
    }
  ]
}'
```

Reset a template

```cURL
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"
    }
  ]
}'
```

### Response codes

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 `value` is supplied with `RESET`.

 |
| 

**401**

 | 

Authentication token is missing, expired, or invalid.

 |
| 

**403**

 | 

The caller does not have the required privilege.

 |
| 

**500**

 | 

Unexpected server error.

 |

## Additional resources

-   [REST API v2.0 Reference]({{navprefix}}/{{rest-api-v2-reference}}#_link_customization)
    
-   [REST API v2.0 changelog]({{navprefix}}/{{rest-apiv2-changelog}})
    
-   [REST API Playground - Search link customizations endpoint]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Flink-customization%2Fsearch-link-customizations)
    
-   [REST API Playground - Update link customizations endpoint]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Flink-customization%2Fupdate-link-customizations)