# Spotter AI agent instructions APIs

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

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

# Spotter AI agent instructions APIs

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]({{navprefix}}/{{spotter-nl-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

<table class="tableblock frame-all grid-all stretch"><colgroup><col style="width: 100%;"></colgroup><tbody><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>PUT /api/rest/2.0/ai/agent/instructions/set</code><br><a href="{{navprefix}}/{{spotter-agent-instructions}}#_set_agent_instructions">Sets behavioral instructions</a> for the Spotter agent.<br><em>Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>GET /api/rest/2.0/ai/agent/instructions/get</code><br><a href="{{navprefix}}/{{spotter-agent-instructions}}#_get_agent_instructions">Retrieves the behavioral instructions</a> currently configured for the Spotter agent.<br><em>Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.</em></p></div></div></td></tr></tbody></table>

## 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 |
| --- | --- |
| 
`instructions`

 | 

_String_. Required. The behavioral instruction text to apply to the Spotter agent. Use natural language to define how Spotter should respond. For example:

-   `"Always respond in English."`
    
-   `"Focus on revenue and margin metrics. Avoid referencing raw row counts unless the user asks."`
    
-   `"When a time period is not specified, default to the current fiscal quarter."`
    





 |

### Example request

```cURL
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 saved AgentInstructions record, which includes the following properties:

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

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

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

```JSON
{
  "instructions": ""
}
```

## Related resources

-   For information about adding instructions at the data model level, see [Data model instruction APIs]({{navprefix}}/{{spotter-nl-instructions}}).
    
-   For information about Spotter agent conversation workflows, see [AI APIs (Spotter Agent and Spotter 3)]({{navprefix}}/{{spotter-agent-apis}}).
    
-   Visit the [REST API v2.0 Playground]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fai%2Fset-agent-instructions) to test the set agent instructions endpoint.
    
-   Visit the [REST API v2.0 Playground]({{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fai%2Fget-agent-instructions) to test the get agent instructions endpoint.