# Spotter agent data literacy APIs > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/spotter-agent-data-literacy-apis # Spotter agent data literacy APIs The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. For information about creating a conversation session, see [Spotter agent conversation APIs]({{navprefix}}/{{spotter-agent-conversation-apis}}). ## Get data source suggestions The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. ### Request parameters | Parameter | Description | | --- | --- | | `metadata_context` | Required. Specify one of the following attributes to set the metadata context: - `data_source_identifiers` _Array of strings_. IDs of the data source object such as Models. - `answer_identifiers` _Array of strings_. GUIDs of the Answer objects that you want to use as metadata. - `conversation_identifier` _String_. ID of the conversation session. - `liveboard_identifiers` _Array of strings_. GUIDs of the Liveboards that you want to use as metadata. | | `query` | _String_. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. | | `limit_relevant_questions` _Optional_ | _Integer_. Sets a limit on the number of sub-questions to return in the response. Default is 5. | | `bypass_cache` _Optional_ | _Boolean_. When set to `true`, disables cache and forces fresh computation. | | `ai_context` _Optional_. | Additional context to guide the response. Define the following attributes as needed: | ### Example request ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "data_source_identifiers": [ "cd252e5c-b552-49a8-821d-3eadaa049cca" ] }, "query": "Net sales of Jackets in west coast", "limit_relevant_questions": 3 }' ``` ### API response If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. ```JSON { "relevant_questions": [ { "query": "What is the trend of sales by type over time?", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" }, { "query": "Sales by item", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" }, { "query": "Sales across regions", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" } ] } ``` The returned results include metadata such as: - `confidence` A float indicating the Model’s confidence in the relevance of each recommendation. - `details` The data source ID, name, and description for each recommended data source. - `reasoning` Reason provided by the LLM to explain why each data source was recommended. ## Get relevant questions The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. ### Request parameters | Parameter | Description | | --- | --- | | `metadata_context` | Required. Specify one of the following attributes to set the metadata context: - `data_source_identifiers` _Array of strings_. IDs of the data source object such as Models. - `answer_identifiers` _Array of strings_. GUIDs of the Answer objects that you want to use as metadata. - `conversation_identifier` _String_. ID of the conversation session. - `liveboard_identifiers` _Array of strings_. GUIDs of the Liveboards that you want to use as metadata. | | `query` | _String_. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. | | `limit_relevant_questions` _Optional_ | _Integer_. Sets a limit on the number of sub-questions to return in the response. Default is 5. | | `bypass_cache` _Optional_ | _Boolean_. When set to `true`, disables cache and forces fresh computation. | | `ai_context` _Optional_. | Additional context to guide the response. Define the following attributes as needed: - `instructions` _Array of strings_. Custom user instructions to influence how the AI interprets and processes the query. - `content` _Array of strings_. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. | ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "data_source_identifiers": [ "cd252e5c-b552-49a8-821d-3eadaa049cca" ] }, "query": "Net sales of Jackets in west coast", "limit_relevant_questions": 3 }' ``` ### Example response If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: - `query` A string containing the natural language (NL) sub-question. - `data_source_identifier` GUID of the data source object. - `data_source_name` Name of the associated data source object. ```JSON { "relevant_questions": [ { "query": "What is the trend of sales by type over time?", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" }, { "query": "Sales by item", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" }, { "query": "Sales across regions", "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", "data_source_name": "(Sample) Retail - Apparel" } ] } ``` ## Additional resources - See also [Spotter Agent APIs]({{navprefix}}/{{spotter-agent-apis}}) - [Spotter agent conversation APIs]({{navprefix}}/{{spotter-agent-conversation-apis}}) - [Process Spotter agent conversation results]({{navprefix}}/{{spotter-agent-process-results-apis}})