# Data model instructions APIs

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

Source: https://developers.thoughtspot.com/docs/spotter-nl-instructions

# Data model instructions APIs

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.

## Setting data model instructions

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 CAN\_MANAGE\_SPOTTER (Can manage Spotter) privilege and either edit access or SPOTTER\_COACHING\_PRIVILEGE permission on the data model. Ensure that your bearer token is scoped to the Org where the data model resides.

### Request parameters

 
| Form parameter | Description |
| --- | --- |
| 
`data_source_identifier`

 | 

_String_. ID of the Model.

 |
| 

`nl_instructions_info`

 | 

Instructions in natural language format.

-   `instructions`  
    _Array of strings_. Include the rules that you want to add in the `instructions` array. Ensure that the instructions don’t exceed 3000 characters.
    
-   `scope`  
    Sets the scope for the rules. By default, the rules are applied globally for all Spotter users who can access the Model specified in the request.
    





 |

### Example request

The following example defines data model instructions that guide Spotter on how to interpret queries:

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

### Example response

If the API request is successful, ThoughtSpot returns the `{"success":true}` response.

## Retrieving data model instructions assigned to a Model

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.

### Request parameters

 
| Form parameter | Description |
| --- | --- |
| 
`data_source_identifier`

 | 

_String_. ID of the Model from which you want to fetch instructions.

 |

### Example request

The following example shows the request body for retrieving data model instructions configured on a Model:

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

### Example response

If the instructions are configured on the Model specified in the API request, ThoughtSpot returns an array of instructions in the API response.

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

## Allowing access to Spotter data model instructions

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.

### Assigning privilege

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
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.

### Retrieving object privilege information for users and groups

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
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:

```JSON
{
   "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":"rani.gangwar@thoughtspot.com",
                     "principal_sub_type":"OIDC_USER",
                     "object_privileges":"[SPOTTER_COACHING_PRIVILEGE]"
                  }
               ]
            }
         ]
      }
   ]
}
```

## Additional resources

-   Visit the [REST API v2.0 Playground]({{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction) to view the API endpoints and verify the request and response workflows.
    
-   For information about the MCP tools, see [MCP server integration]({{navprefix}}/{{mcp-integration}}).