Administrators and data owners can guide and refine how Spotter interprets and answers user questions. The data model instructions API allows you to set instructions at the data model level. The API provides business context and preferred interpretations for specific queries or terminology, but it doesn’t train or change the underlying LLM.
To define how Spotter interprets queries, applies filters, selects columns, handles data nuances, and presents answers using the data from a specific model, you can set global rules in natural language format. Setting data model instructions helps Spotter generate precise and consistent responses for user queries.
To set instructions for a Model, send a POST request to the /api/rest/2.0/ai/instructions/set API endpoint.
|
Note
|
To set data model instructions, you need |
| Form parameter | Description |
|---|---|
| String. ID of the Model. |
| Instructions in natural language format.
|
The following example defines data model instructions that guide Spotter on how to interpret queries:
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/instructions/set' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"data_source_identifier": "71311827-31bb-48b2-8465-9a215adbc05d",
"nl_instructions_info": [
{
"instructions": [
"When I ask for last month, use '\''last 30 days'\'' as a filter.",
"Exclude orders where order_status = '\''CANCELLED-USER'\'' when calculating total revenue"
],
"scope": "GLOBAL"
}
]
}'If the API request is successful, ThoughtSpot returns the {"success":true} response.
To view the data model instructions assigned for a Model, send a POST request to the /api/rest/2.0/ai/instructions/get API endpoint.
Only Spotter users with view access to the data model can retrieve instructions via API requests.
| Form parameter | Description |
|---|---|
| String. ID of the Model from which you want to fetch instructions. |
The following example shows the request body for retrieving data model instructions configured on a Model:
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/instructions/get' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"data_source_identifier": "3bbeac16-a723-4886-9eba-c4779d07fd83"
}'If the instructions are configured on the Model specified in the API request, ThoughtSpot returns an array of instructions in the API response.
{
"nl_instructions_info": [
{
"instructions": [
"When I ask for last month, use 'last 30 days' as a filter.",
"Exclude orders where order_status = 'CANCELLED-USER' when calculating total revenue"
],
"scope": "GLOBAL"
}
]
}ThoughtSpot supports publishing data model instructions to other Orgs. Changes to data model instructions in the primary Org are synchronized with the data models published in secondary Orgs.
To allow users and groups to access data model instructions, assign the SPOTTER_COACHING_PRIVILEGE via POST request to the /api/rest/2.0/security/metadata/manage-object-privilege API endpoint.
In the API request, specify the data model, user, and group, and ensure that the object privilege is set to SPOTTER_COACHING_PRIVILEGE.
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/manage-object-privilege' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"operation": "ADD",
"metadata_type": "LOGICAL_TABLE",
"object_privilege_types": [
"SPOTTER_COACHING_PRIVILEGE"
],
"metadata_identifiers": [
"62f3e9b5-4fcc-4352-b8ad-fdddc2287506"
],
"principals": [
{
"identifier": "UserA",
"type": "USER"
}
]
}'If the request is successful, the API returns the 204 response code.
To get a list of users or groups with the data model instructions privilege (SPOTTER_COACHING_PRIVILEGE) for a specific data model or all data models, send a POST request to the /api/rest/2.0/security/metadata/fetch-object-privileges API endpoint.
In the API request, specify the user or the group for which you want to retrieve the object privilege details.
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/fetch-object-privileges' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"metadata": [
{
"identifier": "53141e3b-331d-4a74-80a2-e4322f9d8339",
"type": "LOGICAL_TABLE"
}
],
"record_offset": 0,
"record_size": 20,
"principals": [
{
"identifier": "UserA",
"type": "USER"
}
]
}'If the request is successful, ThoughtSpot returns the object privilege details in the API response:
{
"metadata_object_privileges":[
{
"metadata_id":"53141e3b-331d-4a74-80a2-e4322f9d8339",
"metadata_name":"Model_formula_variable",
"metadata_type":"WORKSHEET",
"principal_object_privilege_info":[
{
"principal_type":"USER",
"principal_object_privileges":[
{
"principal_id":"0000083e-e253-10af-aa97-5e45d512ebbd",
"principal_name":"[email protected]",
"principal_sub_type":"OIDC_USER",
"object_privileges":"[SPOTTER_COACHING_PRIVILEGE]"
}
]
}
]
}
]
}Visit the REST API v2.0 Playground to view the API endpoints and verify the request and response workflows.
For information about the MCP tools, see MCP server integration.