PUT /api/rest/2.0/ai/agent/instructions/set New
Sets behavioral instructions for the Spotter agent.
Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.
Spotter AI agent instructions APIs
Table of Contents
Administrators and developers can configure persistent behavioral instructions for the Spotter agent using agent instructions APIs. These instructions guide how Spotter responds within a conversation context. For example, to focus on specific business domains, enforce response formats, or apply analytical constraints.
Unlike data model instructions, which operate at the data model level, agent instructions operate at the agent level and do not require a data source identifier.
Supported API endpoints🔗
|
Set agent instructions🔗
The PUT /api/rest/2.0/ai/agent/instructions/set API endpoint sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries.
Instructions persist until you overwrite or remove them by sending a new PUT request.
Prerequisites🔗
To configure agent instructions, you need administration or CAN_MANAGE_SPOTTER (Can manage Spotter) privilege.
Request parameters🔗
| Parameter | Description |
|---|---|
| String. Required. The behavioral instruction text to apply to the Spotter agent. Use natural language to define how Spotter should respond. For example:
|
Example request🔗
curl -X PUT \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/instructions/set' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"instructions": "Always respond in English. Focus on revenue and margin metrics. When a time period is not specified, default to the current fiscal quarter."
}'Example response🔗
If the API request is successful, ThoughtSpot returns an HTTP 200 response with the following agent instruction properties:
If the request is successful, the response includes the saved AgentInstructions record:
-
id: unique identifier of the record -
instructions: the saved instructions text -
created_at: ISO timestamp when the instructions were first created -
updated_at: ISO timestamp of this update -
last_updated_by: user ID of the admin who performed this update
If the request fails, ThoughtSpot returns an error code and message. For example, if the REST client doesn’t have the permission to set agent instructions, the following example shows an authorization error:
{
"error_code": "UNAUTHORIZED",
"message": "You do not have permission to set agent instructions."
}Get agent instructions🔗
The GET /api/rest/2.0/ai/agent/instructions/get API endpoint retrieves the behavioral instructions currently configured for the Spotter agent.
Prerequisites🔗
To retrieve agent instructions via REST API, you need administration privileges.
Request parameters🔗
This endpoint does not require a request body or query parameters.
Example request🔗
curl -X GET \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/instructions/get' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}'Example response🔗
If the API request is successful and instructions are configured, ThoughtSpot returns the current instructions in the response body.
{
"instructions": "Always respond in English. Focus on revenue and margin metrics. When a time period is not specified, default to the current fiscal quarter."
}If no instructions are configured, ThoughtSpot returns an empty value for the instructions field.
{
"instructions": ""
}Related resources🔗
-
For information about adding instructions at the data model level, see Data model instruction APIs.
-
For information about Spotter agent conversation workflows, see AI APIs (Spotter Agent and Spotter 3).
-
Visit the REST API v2.0 Playground to test the set agent instructions endpoint.
-
Visit the REST API v2.0 Playground to test the get agent instructions endpoint.