openapi: 3.0.0
info:
  title: ThoughtSpot Public REST 10.1.0.cl AI API
  version: '2.0'
servers:
- url: '{base-url}'
  variables:
    base-url:
      default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: AI
paths:
  /api/rest/2.0/ai/agent/conversation/create:
    post:
      operationId: createAgentConversation
      description: "\n <span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\n<span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\nCreates a new Spotter agent conversation based on the provided context and settings. The endpoint was in Beta from 26.2.0.cl through 26.4.0.cl.\n\nRequires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.\n\n#### Usage guidelines\n\nThe request must include the `metadata_context` parameter to define the conversation context. The context type can be one of:\n\n- `DATA_SOURCE` *(available from 26.5.0.cl)*: targets a specific data source. Provide `data_source_identifier` in `data_source_context` for a single data source, or `data_source_identifiers` for multi-data-source context. The deprecated `guid` field is accepted for backwards compatibility.\n- `AUTO_MODE` *(available from 26.5.0.cl)*: automatically discovers and selects the most relevant datasets for the user's queries.\n\n> **Note for callers on versions 26.2.0.cl – 26.4.0.cl (Beta):** use the lowercase `data_source` enum value with the `guid` field instead of the above. Example: `{ \"type\": \"data_source\", \"data_source_context\": { \"guid\": \"<worksheet-id>\" } }`.\n\nThe `conversation_settings` parameter controls which Spotter capabilities are enabled for the conversation:\n\n- `enable_contextual_change_analysis` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_natural_language_answer_generation` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_reasoning` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_save_chat` (default: `false`, *available from 26.5.0.cl*) — enables saving the conversation for later retrieval via conversation history\n\nIf the request is successful, the response includes a unique `conversation_identifier` that must be passed to `sendAgentConversationMessage` or `sendAgentConversationMessageStreaming` to send messages within this conversation. The response also includes `conversation_id` with the same value for backwards compatibility; use `conversation_identifier` for new integrations.\n\n#### Example request\n\n```json\n{\n  \"metadata_context\": {\n    \"type\": \"DATA_SOURCE\",\n    \"data_source_context\": {\n      \"data_source_identifier\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n    }\n  },\n  \"conversation_settings\": {}\n}\n```\n\n#### Error responses\n\n| Code | Description                                                                                                                             |\n| ---- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                    |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the specified metadata object. |\n\n> ###### Note:\n>\n> - This endpoint was in Beta from 26.2.0.cl through 26.4.0.cl and is Generally Available from version 26.5.0.cl.\n> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentConversationRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversation'
              examples:
                example_1:
                  summary: Create a conversation with a specific data source
                  value:
                    conversation_id: wwHQ5j8O8dQC
                    conversation_identifier: wwHQ5j8O8dQC
                example_2:
                  summary: Create a conversation using auto mode where the agent automatically discovers and selects the most relevant datasets for the user's queries
                  value:
                    conversation_id: aaHQ5j8O8dQC
                    conversation_identifier: aaHQ5j8O8dQC
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversation'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/conversation/create:
    post:
      operationId: createConversation
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>


        <span class="since-beta-tag">Version: 10.4.0.cl or later</span>


        Creates a new conversation session tied to a specific data model for AI-driven natural language querying.


        Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.


        #### Usage guidelines


        The request must include:

        - `metadata_identifier`: the unique ID of the data source that provides context for the conversation


        Optionally, you can provide:

        - `tokens`: a token string to set initial context for the conversation (e.g., `"[sales],[item type],[state]"`)


        If the request is successful, ThoughtSpot returns a unique `conversation_identifier` that must be passed to `sendMessage` to continue the conversation.


        #### Error responses


        | Code | Description |

        |------|-------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid. |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the specified metadata object. |


        > ###### Note:

        > * This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > * This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete:
    delete:
      operationId: deleteConversation
      description: '

        Deletes an existing agent conversation. <br/>  <span class="since-beta-tag">Version: 26.7.0.cl or later</span>


        Permanently deletes an existing saved agent conversation and all its associated messages. This operation is irreversible — deleted conversations cannot be recovered.


        Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation being deleted.


        #### Usage guidelines


        The request must include:


        - `conversation_identifier` *(path parameter)*: the unique ID of the conversation to delete, as returned by `createAgentConversation` or `getConversationList`


        A successful request returns an empty `204 No Content` response. The deleted conversation no longer appears in `getConversationList`.


        #### Example request


        ```bash

        DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete

        ```


        #### Error responses


        | Code | Description |

        |------|-------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid. |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or does not own the specified conversation. |

        | 404  | Not Found — no conversation exists with the given `conversation_identifier` for the authenticated user. |


        > ###### Note:

        >

        > - Deletion is permanent and cannot be undone. Ensure the correct `conversation_identifier` is used before calling this endpoint.

        > - Only conversations created with `enable_save_chat: true` are persisted and can be deleted via this endpoint.

        > - Available from version 26.7.0.cl and later.

        > - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation to delete.
      responses:
        '204':
          description: Successfully deleted the agent conversation.
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/memory/export:
    post:
      operationId: exportMemory
      description: "\nExports memory entries (rules, recipes, and always-apply rules) for\nthe specified data-models as a single YAML payload. The payload can\nbe edited locally and re-submitted through `importMemory`.\nRequires Spotter access (use/manage) and either edit or memory\naccess on corresponding data model sources. <br/> <span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 26.8.0.cl or later</span>\n\nThis API allows users to export data-model memories for a given list of data-models. This exported yaml file can then be modified and used as input to the import API in target env.\n\nThis API enables customers to migrate memories from a source env to a target env. This improves memory adoption for Spotter by giving the users a chance to develop their memories in one env and replicate the same in another env.\n\n#### Usage guidelines\n\nTo export memory for one or more data-models, the request may include:\n- `sources`: A list of typed scope groups identifying which data-models to export memory for. Each group contains:\n  - `type`: The source object type for this group — `DATA_MODEL`.\n  - `identifiers`: An array of GUIDs or human-readable `obj_id`s of the data-models to export memory for. obj_ids are resolved server-side before forwarding.\n\nThe API returns a response object with:\n- `content`: The serialized memory payload (YAML) — exactly the shape that the `importMemory` API consumes. Edit it locally and pass it back through `importMemory` to apply changes.\n\n#### Source Type\n\n- **DATA_MODEL**: The `identifiers` are data-model GUIDs. This is the default source type for Spotter memory and covers the rules, recipes and always-apply rules attached directly to a data-model.\n\n#### File format\n\nThe exported `content` is a YAML document with a single top-level `memories` key holding a list of memory items — exactly the format the `importMemory` API consumes. The full format reference (an annotated example, memory item fields, per-type content, and `datamodel_sources` identification) is documented in the `importMemory` API's **File format** section. Exported files populate each source's `guid` and, if present, `obj_id` as well.\n\n#### Error responses\n\n| Code | Description                                                                                                                                                                                  |\n|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                                                                         |\n| 403  | Forbidden — the authenticated user does not have necessary permissions, or lacks read access on a referenced data-model, or the bearer token does not correspond to the data-model's org. |\n\n> ###### Note:\n> - To use this API, the user needs Spotter access (use/manage) and either edit or memory access on the data-model and they must use corresponding org related bearerToken where the data-model exists.\n> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.\n> - Available from version 26.8.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportMemoryRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportMemoryResponse'
              examples:
                example_1:
                  summary: Serialized YAML memory payload returned
                  value:
                    content: "memories:\n- type: RULE\n  content:\n    rule_definition: \"Earnings: total sales filtered to West region only.\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition: \"Geographic data is organized in a three-level hierarchy from broadest to most specific: Region (highest level) → State (middle level) → County (lowest level). This hierarchical structure enables progressive drill-down analysis, where each level provides increasingly granular geographic segmentation for sales and quantity metrics.\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition: \"Hot products: top 5 products by total sales (no region filter applied).\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: Calculate earnings for East region current year\n    recipe: \"{\\\"task\\\": \\\"Compute earnings by extracting sales and filtering to East region for the current year\\\", \\\"steps\\\": [{\\\"instruction\\\": \\\"Extract sales, then apply a filter for current year and a filter for East region.\\\", \\\"analytical_mappings\\\": {\\\"tml_tokens\\\": [\\\"[sales] [date] = 'this year' [region] = 'east'\\\"], \\\"formulas\\\": []}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: Total sales for East region current year\n    recipe: \"{\\\"task\\\": \\\"Compute total sales filtered to East region for the current year\\\", \\\"steps\\\": [{\\\"instruction\\\": \\\"Calculate total sales where region is East and date is current year.\\\", \\\"analytical_mappings\\\": {\\\"tml_tokens\\\": [\\\"[sales] [date] = 'this year' [region] = 'east'\\\"], \\\"formulas\\\": []}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: What is the total quantity purchased by city and region?\n    recipe: \"{\\\"task\\\":\\\"Calculate total quantity purchased grouped by city and region\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Sum the quantity purchased metric and group the results by city and region to show purchasing volumes across different geographic locations\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[quantity purchased] [city] [region]\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: What were total jacket sales in 2024?\n    recipe: \"{\\\"task\\\":\\\"Compute the aggregate 2024 jacket sales revenue.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Shows the total sales revenue for jackets in 2024. This provides a high-level metric to understand overall jacket sales performance for the year.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [item type] = [item type].\\\\\\\"jackets\\\\\\\" [date] = \\\\\\\"2024\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: How are monthly sales and quantity tracking by state?\n    recipe: \"{\\\"task\\\":\\\"Aggregate monthly sales and quantity by state for a state-level performance view.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Shows monthly sales and quantity purchased metrics organized by state. Provides a state-wise view of sales performance with additional dimensional context.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [state] [date]\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: \"What's the quarterly sales and quantity by region and state for the last 3 years, with yearly rollups?\"\n    recipe: \"{\\\"task\\\":\\\"Build a 3-year quarterly view of sales and quantity grouped by region and state, with quarterly and yearly aggregation.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Displays quarterly performance metrics including sales and quantity purchased, broken down by region and state over the last 3 years. Enables analysis of regional and state-level trends with both quarterly and yearly views.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [region] [state] [date].\\\\\\\"quarterly\\\\\\\" [date].\\\\\\\"last 3 years\\\\\\\" [date].\\\\\\\"yearly\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: How are we doing against quarterly sales and quantity targets per region?\n    recipe: \"{\\\"task\\\":\\\"Render bullet charts contrasting quarterly actual vs target sales and quantity per region.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Compares actual quarterly sales and quantity metrics against targets by region using bullet charts. Provides a target vs actual performance view to track progress.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [region] [date].\\\\\\\"quarterly\\\\\\\" [Target sales] [Target quantity]\\\"],\\\"formulas\\\":[\\\"{\\\\\\\"name\\\\\\\": \\\\\\\"Target sales\\\\\\\", \\\\\\\"expression\\\\\\\": \\\\\\\"random ( ) * sum ( sales ) * 2\\\\\\\"}\\\",\\\"{\\\\\\\"name\\\\\\\": \\\\\\\"Target quantity\\\\\\\", \\\\\\\"expression\\\\\\\": \\\\\\\"random ( ) * sum ( quantity purchased  ) * 2\\\\\\\"}\\\"]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n"
                example_2:
                  summary: Serialized YAML memory payload returned
                  value:
                    content: "memories:\n- type: RULE\n  content:\n    rule_definition: \"Earnings: total sales filtered to West region only.\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition: \"Hot products: top 5 products by total sales (no region filter applied).\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition: \"Geographic data is organized in a three-level hierarchy from broadest to most specific: Region (highest level) → State (middle level) → County (lowest level). This hierarchical structure enables progressive drill-down analysis, where each level provides increasingly granular geographic segmentation for sales and quantity metrics.\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition: \"When analyzing quantity purchased, apply a date filter for the last 3 years.\"\n  datamodel_sources:\n  - guid: 44444444-4444-4444-4444-444444444444\n    obj_id: sample-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition:  User's total sales target is 1 million USD.\n  datamodel_sources:\n  - guid: 44444444-4444-4444-4444-444444444444\n    obj_id: sample-model\n  tags: []\n- type: RULE\n  content:\n    rule_definition:  Sales analyses must filter to east region only.\n  datamodel_sources:\n  - guid: 44444444-4444-4444-4444-444444444444\n    obj_id: sample-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: Calculate earnings for East region current year\n    recipe: \"{\\\"task\\\": \\\"Compute earnings by extracting sales and filtering to East region for the current year\\\", \\\"steps\\\": [{\\\"instruction\\\": \\\"Extract sales, then apply a filter for current year and a filter for East region.\\\", \\\"analytical_mappings\\\": {\\\"tml_tokens\\\": [\\\"[sales] [date] = 'this year' [region] = 'east'\\\"], \\\"formulas\\\": []}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: Total sales for East region current year\n    recipe: \"{\\\"task\\\": \\\"Compute total sales filtered to East region for the current year\\\", \\\"steps\\\": [{\\\"instruction\\\": \\\"Calculate total sales where region is East and date is current year.\\\", \\\"analytical_mappings\\\": {\\\"tml_tokens\\\": [\\\"[sales] [date] = 'this year' [region] = 'east'\\\"], \\\"formulas\\\": []}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: What is the total quantity purchased by city and region?\n    recipe: \"{\\\"task\\\":\\\"Calculate total quantity purchased grouped by city and region\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Sum the quantity purchased metric and group the results by city and region to show purchasing volumes across different geographic locations\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[quantity purchased] [city] [region]\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: \"What's the quarterly sales and quantity by region and state for the last 3 years, with yearly rollups?\"\n    recipe: \"{\\\"task\\\":\\\"Build a 3-year quarterly view of sales and quantity grouped by region and state, with quarterly and yearly aggregation.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Displays quarterly performance metrics including sales and quantity purchased, broken down by region and state over the last 3 years. Enables analysis of regional and state-level trends with both quarterly and yearly views.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [region] [state] [date].\\\\\\\"quarterly\\\\\\\" [date].\\\\\\\"last 3 years\\\\\\\" [date].\\\\\\\"yearly\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: How are we doing against quarterly sales and quantity targets per region?\n    recipe: \"{\\\"task\\\":\\\"Render bullet charts contrasting quarterly actual vs target sales and quantity per region.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Compares actual quarterly sales and quantity metrics against targets by region using bullet charts. Provides a target vs actual performance view to track progress.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [region] [date].\\\\\\\"quarterly\\\\\\\" [Target sales] [Target quantity]\\\"],\\\"formulas\\\":[\\\"{\\\\\\\"name\\\\\\\": \\\\\\\"Target sales\\\\\\\", \\\\\\\"expression\\\\\\\": \\\\\\\"random ( ) * sum ( sales ) * 2\\\\\\\"}\\\",\\\"{\\\\\\\"name\\\\\\\": \\\\\\\"Target quantity\\\\\\\", \\\\\\\"expression\\\\\\\": \\\\\\\"random ( ) * sum ( quantity purchased  ) * 2\\\\\\\"}\\\"]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: How are monthly sales and quantity tracking by state?\n    recipe: \"{\\\"task\\\":\\\"Aggregate monthly sales and quantity by state for a state-level performance view.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Shows monthly sales and quantity purchased metrics organized by state. Provides a state-wise view of sales performance with additional dimensional context.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [state] [date]\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: What were total jacket sales in 2024?\n    recipe: \"{\\\"task\\\":\\\"Compute the aggregate 2024 jacket sales revenue.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Shows the total sales revenue for jackets in 2024. This provides a high-level metric to understand overall jacket sales performance for the year.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [item type] = [item type].\\\\\\\"jackets\\\\\\\" [date] = \\\\\\\"2024\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 33333333-3333-3333-3333-333333333333\n    obj_id: sales-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: What were jacket sales by region in 2024?\n    recipe: \"{\\\"task\\\":\\\"Break out 2024 jacket sales revenue by region to compare regional performance.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Shows jacket sales revenue broken down by region for 2024. This helps identify which geographic regions are performing best in jacket sales and enables regional performance comparison.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] by [region] [item type] = [item type].\\\\\\\"jackets\\\\\\\" [date] = \\\\\\\"2024\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 44444444-4444-4444-4444-444444444444\n    obj_id: sample-model\n  tags: []\n- type: RECIPE\n  content:\n    user_query: \"Show me quarterly sales and quantity trends over the past 3 years, newest first.\"\n    recipe: \"{\\\"task\\\":\\\"Plot quarterly sales and quantity trends for the past 3 years in reverse chronological order.\\\",\\\"steps\\\":[{\\\"instruction\\\":\\\"Presents quarterly sales and quantity purchased trends over the last 3 years, sorted by most recent periods first. Enables time-based analysis of sales performance.\\\",\\\"analytical_mappings\\\":{\\\"tml_tokens\\\":[\\\"[sales] [quantity purchased] [date].\\\\\\\"quarterly\\\\\\\" [date].\\\\\\\"last 3 years\\\\\\\"\\\"],\\\"formulas\\\":[]}}]}\"\n  datamodel_sources:\n  - guid: 44444444-4444-4444-4444-444444444444\n    obj_id: sample-model\n  tags: []\n"
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportMemoryResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/instructions/get:
    get:
      operationId: getAgentInstructions
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.6.0.cl or later</span>


        Retrieves the admin instructions currently configured for the AI agent (Spotter). Admin instructions are tenant- and org-scoped text that guide agent behavior across all conversations.


        Requires admin privileges. Only users with org admin access can retrieve agent instructions.


        #### Usage guidelines


        No input parameters are required. The API returns the stored `AgentInstructions` record for the caller''s tenant and org.


        If no instructions have been configured yet, the API returns a record with an empty `instructions` field and `null` values for `id`, `created_at`, `updated_at`, and `last_updated_by`.


        If the request is successful, the response includes:


        - `id`: unique identifier of the instructions record

        - `instructions`: the configured instructions text

        - `created_at`: ISO timestamp when the instructions were first saved

        - `updated_at`: ISO timestamp when the instructions were last updated

        - `last_updated_by`: user ID of the admin who last updated the instructions (may be `null` for older records)


        #### Error responses


        | Code | Description |

        |------|-------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid. |

        | 403  | Forbidden — the authenticated user does not have org admin privileges required to read agent instructions. |


        > ###### Note:

        >

        > - Use `setAgentInstructions` to create or update agent instructions.

        > - Available from version 26.6.0.cl and later.





        #### Endpoint URL

        '
      tags:
      - AI
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstructions'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstructions'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages:
    get:
      operationId: getConversation
      description: "\nRetrieves the full public-safe content of a saved agent conversation: ordered\nturns (user messages and agent response items) and sanitized code-execution\nfile metadata. Internal graph or branch state, Azure file identifiers, and\nmessages with a `SYSTEM` source are omitted. The full answer payload is not\nembedded; fetch it separately via `loadAnswer` using the `answer_id` on each\n`answer` response item.\nRequires `CAN_USE_SPOTTER` privilege and access to the specified conversation. <br/>  <span class=\"since-beta-tag\">Version: 26.7.0.cl or later</span>\n\nRetrieves the full public-safe content of a saved agent conversation. Returns ordered conversation messages — each carrying an optional user prompt (the user's message and any attachments) and the agent response items produced for that turn — plus sanitized metadata for any files generated by the code-execution tool. \n\nUse this endpoint to render a persisted conversation in a UI, build an audit trail, or post-process a completed conversation. The full answer payload is not embedded — fetch it separately via `loadAnswer` using the `answer_id` on each `answer` response item.\n\nRequires `CAN_USE_SPOTTER` privilege and access to the specified conversation.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier` _(path parameter)_: the unique ID of the conversation, as returned by `createAgentConversation` or `getConversationList`.\n\nIf the request is successful, the response contains two top-level fields:\n\n| Field                  | Type                                        | Description                                                                                                                                          |\n| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `messages`             | `ConversationMessage[]`                     | Ordered oldest to newest. Empty array when the conversation has no messages.                                                                         |\n| `code_execution_files` | `CodeExecutionFileMetadata[]`               | List of sanitized file metadata entries (one per `file_id`). Covers all code-execution-generated files referenced anywhere in the conversation. Empty array when there are none. |\n\nNo other top-level fields are returned.\n\n#### ConversationMessage fields\n\n| Field                 | Type                         | Description                                                                                                    |\n| --------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| `message_id`          | `String`                     | Stable identifier for the turn. For liveboard-started synthetic first turns, this is the root node identifier. |\n| `timestamp_in_millis` | `Long`                       | Milliseconds since Unix epoch for the turn.                                                                    |\n| `user_prompt`         | `UserPrompt`                 | User-authored prompt that started the turn (message and attachments). `null` for liveboard-started synthetic first turns. |\n| `response_items`      | `ConversationResponseItem[]` | Agent-side output produced in response to this turn. Empty array for in-progress turns.                        |\n\n#### UserPrompt fields\n\n| Field         | Type                   | Description                                                                                          |\n| ------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |\n| `message`     | `UserMessage`          | User query that started the turn. `null` for liveboard-started synthetic first turns.                |\n| `attachments` | `UserAttachmentItem[]` | Files or connector resources attached to the user message. Empty array when there are no attachments. |\n\n#### UserMessage fields\n\n| Field        | Type     | Description                                   |\n| ------------ | -------- | --------------------------------------------- |\n| `message_id` | `String` | Unique identifier of the user-source message. |\n| `content`    | `String` | Text body of the user query.                  |\n\n#### UserAttachmentItem fields\n\nDiscriminated by `type`. Only `\"file\"` or `\"resource\"` are valid values. Only the fields for the indicated variant are populated. See `ConversationResponseItem` below for the field definitions of the `file` and `resource` variants — `UserAttachmentItem` uses the same fields.\n\n#### ConversationResponseItem fields\n\nEvery item carries a `type` discriminator and these shared fields:\n\n| Field                 | Type      | Description                                                                                                                    |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `type`                | `String`  | Discriminator. One of `\"text\"`, `\"tool_call\"`, `\"tool_result\"`, `\"answer\"`, `\"file\"`, `\"resource\"`, `\"search_datasets\"`.       |\n| `timestamp_in_millis` | `Long`    | Milliseconds since Unix epoch when this item was produced.                                                                     |\n| `is_thinking`         | `Boolean` | `true` when the item represents internal agent reasoning rather than user-facing output. Consumers may hide or collapse these. |\n| `step_title`          | `String`  | Human-readable label for the agent step producing this item (e.g. `\"Searching\"`, `\"Visualising\"`).                             |\n\nVariant-specific fields:\n\n- **`text`** — agent text output: `content` (String), `content_type` (`ContentMimeType` enum), `file_reference` (FileReference).\n- **`tool_call`** — agent invoked a tool: `tool_call_id` (String), `tool_name` (String), `arguments` (JSON object).\n- **`tool_result`** — result returned from a tool invocation: `tool_call_id`, `tool_name`, `content`, `content_type` (`ContentMimeType` enum), `success` (Boolean).\n- **`answer`** — slim reference to a saved answer: `answer_id` (String), `tool_call_id`, `tool_name`.\n- **`file`** — uploaded or generated files: `files` (`PublicFileInfo[]`).\n- **`resource`** — MCP connector resource: `title`, `uri`, `name`, `mime_type`, `description`, `size` (Int), `connector_id`, `connector_name`, `connector_slug`, `transport_type` (`TransportType` enum).\n- **`search_datasets`** — dataset discovery result: `text` (String), `data_sources` (`DataSourceInfo[]`).\n\nClients should switch on `type` and ignore unknown variants for forward-compatibility.\n\n#### content_type values\n\n`content_type` is the `ContentMimeType` enum. The following values are defined:\n\n| Value                       | Wire MIME                   | Meaning                                              |\n| --------------------------- | --------------------------- | ---------------------------------------------------- |\n| `TEXT_PLAIN`                | `text/plain`                | Plain text. Default for `tool_result`.               |\n| `TEXT_MARKDOWN`             | `text/markdown`             | Markdown. Default for `text`.                        |\n| `TEXT_X_MARKDOWN_WITH_CODE` | `text/x-markdown-with-code` | Markdown whose body starts with a fenced code block. |\n| `TEXT_HTML`                 | `text/html`                 | Raw HTML.                                            |\n\n#### transport_type values\n\n`transport_type` is the `TransportType` enum used on the `resource` variant.\n\n| Value              | Meaning                                       |\n| ------------------ | --------------------------------------------- |\n| `STREAMABLE_HTTP`  | Streamable HTTP transport (default for MCP).  |\n| `SSE`              | Server-sent events transport.                 |\n\n#### FileReference fields\n\n| Field                    | Type     | Description                                                  |\n| ------------------------ | -------- | ------------------------------------------------------------ |\n| `file_id`                | `String` | Unique identifier of the code-execution-generated file.      |\n| `display_name`           | `String` | Human-readable file name.                                    |\n| `created_time_in_millis` | `Long`   | Milliseconds since Unix epoch when the file was created.     |\n\nCross-reference `file_id` against `code_execution_files` to retrieve full metadata including the `expired` flag before attempting a download.\n\n#### PublicFileInfo fields\n\n| Field                    | Type     | Description                                              |\n| ------------------------ | -------- | -------------------------------------------------------- |\n| `file_id`                | `String` | Unique identifier of the file.                           |\n| `display_name`           | `String` | Human-readable file name.                                |\n| `file_type`              | `String` | File type such as `csv`, `pdf`, or `png`.                |\n| `created_time_in_millis` | `Long`   | Milliseconds since Unix epoch when the file was created. |\n| `size_bytes`             | `Int`    | File size in bytes.                                      |\n\n#### CodeExecutionFileMetadata fields\n\nEach entry in the `code_execution_files` array contains:\n\n| Field                    | Type      | Description                                                                                                                     |\n| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `file_id`                | `String`  | Unique identifier of the file.                                                                                                  |\n| `display_name`           | `String`  | Human-readable file name.                                                                                                       |\n| `file_type`              | `String`  | File type such as `csv`, `pdf`, or `png`.                                                                                       |\n| `created_time_in_millis` | `Long`    | Milliseconds since Unix epoch when the file was created.                                                                        |\n| `expired`                | `Boolean` | When `true`, the underlying file is no longer retrievable from code-execution storage; UIs should disable download and preview. |\n\n#### Loading answer payloads\n\nEach `AnswerResponseItem` in the response contains an `answer_id` field. Pass this value as the `answer_identifier` parameter to `loadAnswer` to retrieve the full answer payload (TML tokens, visualization metadata) for that item.\n\n#### Example request\n\n```bash\nGET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages\n```\n\n#### Example response\n\n```json\n{\n  \"messages\": [\n    {\n      \"message_id\": \"node_u_01\",\n      \"timestamp_in_millis\": 1744000000000,\n      \"user_prompt\": {\n        \"message\": {\n          \"message_id\": \"msg_u_01\",\n          \"content\": \"Show me revenue by region as a chart.\"\n        },\n        \"attachments\": []\n      },\n      \"response_items\": [\n        {\n          \"type\": \"tool_call\",\n          \"tool_call_id\": \"toolu_01ABC\",\n          \"tool_name\": \"search_datasets\",\n          \"step_title\": \"Searching datasets\",\n          \"arguments\": { \"query\": \"revenue\" },\n          \"timestamp_in_millis\": 1744000001000,\n          \"is_thinking\": false\n        },\n        {\n          \"type\": \"answer\",\n          \"answer_id\": \"ans_01XYZ\",\n          \"tool_call_id\": \"toolu_02DEF\",\n          \"tool_name\": \"fetch_and_visualize\",\n          \"step_title\": \"Visualising\",\n          \"timestamp_in_millis\": 1744000004000,\n          \"is_thinking\": false\n        },\n        {\n          \"type\": \"text\",\n          \"content\": \"Revenue is highest in APAC.\",\n          \"content_type\": \"TEXT_MARKDOWN\",\n          \"timestamp_in_millis\": 1744000005000,\n          \"is_thinking\": false,\n          \"step_title\": null,\n          \"file_reference\": {\n            \"file_id\": \"revenue_by_region.csv\",\n            \"display_name\": \"revenue_by_region.csv\",\n            \"created_time_in_millis\": 1744027200000\n          }\n        }\n      ]\n    }\n  ],\n  \"code_execution_files\": [\n    {\n      \"file_id\": \"revenue_by_region.csv\",\n      \"display_name\": \"revenue_by_region.csv\",\n      \"file_type\": \"csv\",\n      \"created_time_in_millis\": 1744027200000,\n      \"expired\": false\n    }\n  ]\n}\n```\n\n#### Example: liveboard-started conversation\n\nWhen a conversation is initiated from a saved liveboard visualization rather than a user query, the first turn is synthetic. `user_prompt` is `null`, and `response_items` contains a single `answer` item referencing the seed visualization.\n\n```json\n{\n  \"messages\": [\n    {\n      \"message_id\": \"ROOT_NODE\",\n      \"timestamp_in_millis\": 1743999000000,\n      \"user_prompt\": null,\n      \"response_items\": [\n        {\n          \"type\": \"answer\",\n          \"answer_id\": \"lb_seed_01\",\n          \"tool_call_id\": null,\n          \"tool_name\": null,\n          \"step_title\": null,\n          \"timestamp_in_millis\": 1743999000000,\n          \"is_thinking\": false\n        }\n      ]\n    }\n  ],\n  \"code_execution_files\": []\n}\n```\n\nSubsequent turns follow the normal user-to-agent pattern.\n\n#### Error responses\n\n| Code | Description                                                                                                                 |\n| ---- | --------------------------------------------------------------------------------------------------------------------------- |\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                        |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks access to the specified conversation. |\n| 404  | Not Found — no conversation exists with the given identifier for the authenticated user.                                    |\n\n> ###### Note:\n>\n> - Messages with an internal `SYSTEM` source are always dropped from the response.\n> - In-progress turns are still returned with an empty `response_items` array so clients can render the user message immediately.\n> - Do not assume every `tool_call` has a paired `tool_result` or `answer` — an interrupted conversation can leave a dangling call.\n> - Available from version 26.7.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation to load.
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessageResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessageResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations:
    get:
      operationId: getConversationList
      description: "\nRetrieves the list of saved agent conversations for the currently authenticated user.\nOnly conversations created with `enable_save_chat: true` are returned. <br/>  <span class=\"since-beta-tag\">Version: 26.7.0.cl or later</span>\n\nRetrieves a paginated list of saved agent conversations for the currently authenticated user. Only conversations that were created with `enable_save_chat: true` in `createAgentConversation` are returned.\n\nRequires `CAN_USE_SPOTTER` privilege.\n\n#### Usage guidelines\n\nThe request supports the following optional query parameters:\n\n- `limit`: maximum number of conversations to return. Use this together with `offset` for pagination.\n- `offset`: number of conversations to skip before returning results. Defaults to `0`.\n- `skip_empty`: when `true` (default), conversations with no messages are excluded from the results. Set to `false` to include empty conversations.\n\nIf the request is successful, the response includes a `conversations` array. Each entry contains:\n\n- `conversation_identifier`: the unique ID of the conversation, used as input to `sendAgentConversationMessage`, `updateConversation`, `deleteConversation`, `stopConversation`, and `loadAnswer`\n- `conversation_title`: the display name of the conversation\n- `created_at`: ISO 8601 timestamp of when the conversation was created\n- `updated_at`: ISO 8601 timestamp of the most recent update to the conversation\n- `data_source_identifiers`: list of unique IDs of the data sources associated with the conversation\n- `data_source_names`: array of `{ id, name }` objects for the data sources associated with the conversation\n\n#### Pagination\n\nUse `limit` and `offset` to page through large result sets:\n\n```\nGET /api/rest/2.0/ai/agent/conversations?limit=20&offset=0   → first page\nGET /api/rest/2.0/ai/agent/conversations?limit=20&offset=20  → second page\n```\n\n#### Pagination and `has_more`\n\nThe response includes a `has_more: Boolean` field. When `true`, there are additional conversations beyond the current page — increment `offset` by `limit` to fetch the next page. When `has_more` is `false`, the current page is the last. Note that `total_count` is not returned; use `has_more` to drive paging controls.\n\n#### Example response\n\n```json\n{\n  \"conversations\": [\n    {\n      \"conversation_identifier\": \"abc123\",\n      \"conversation_title\": \"Sales by Region Q1\",\n      \"created_at\": \"2026-03-01T10:00:00Z\",\n      \"updated_at\": \"2026-03-05T14:23:00Z\",\n      \"data_source_identifiers\": [\"ds-001\"],\n      \"data_source_names\": [{ \"id\": \"ds-001\", \"name\": \"Retail Sales\" }]\n    }\n  ],\n  \"has_more\": false\n}\n```\n\n#### Error responses\n\n| Code | Description |\n|------|-------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege. |\n\n> ###### Note:\n>\n> - Only conversations created with `enable_save_chat: true` appear in this list. Conversations created with `enable_save_chat: false` (the default) are not persisted and cannot be retrieved.\n> - Available from version 26.7.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int32
          default: 30
        description: Maximum number of conversations to return. Used for pagination.
      - in: query
        name: offset
        required: false
        schema:
          type: integer
          format: int32
          default: 0
        description: Number of conversations to skip before returning results. Used for pagination.
      - in: query
        name: skip_empty
        required: false
        schema:
          type: boolean
          default: true
        description: When true, excludes conversations with no messages. Defaults to true.
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationHistoryResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationHistoryResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/data-source-suggestions:
    post:
      operationId: getDataSourceSuggestions
      description: "\n<span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 10.15.0.cl or later</span>\n\nSuggests the most relevant data sources for a given natural language query, ranked by confidence with LLM-generated reasoning.\n\nRequires `CAN_USE_SPOTTER` privilege and at least view-level access to the underlying metadata entities referenced in the response.\n\n#### Usage guidelines\n\nThe request must include:\n- `query`: the natural language question to find relevant data sources for\n\nIf the request is successful, the API returns a ranked list of suggested data sources, each containing:\n- `confidence`: a float score indicating the model's confidence in the relevance of the suggestion\n- `details`: metadata about the data source\n  - `data_source_identifier`: the unique ID of the data source\n  - `data_source_name`: the display name of the data source\n  - `description`: a description of the data source\n- `reasoning`: LLM-generated rationale explaining why the data source was recommended\n\n#### Error responses\n\n| Code | Description                                                                                                                                |\n|------|--------------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                       |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the underlying metadata entities. |\n\n> ###### Note:\n> * This endpoint is currently in Beta. Breaking changes may be introduced before it is made Generally Available.\n> * This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDataSourceSuggestionsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_DataSourceSuggestionResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_DataSourceSuggestionResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/instructions/get:
    post:
      operationId: getNLInstructions
      description: "\n<span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 10.15.0.cl or later</span>\n\nRetrieves existing natural language (NL) instructions configured for a specific data model. These instructions guide the AI system in understanding data context and generating more accurate responses.\n\nRequires `CAN_USE_SPOTTER` privilege, at least view access on the data model, and a bearer token corresponding to the org where the data model exists.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `data_source_identifier`: the unique ID of the data model to retrieve instructions for\n\nIf the request is successful, the API returns:\n\n- `nl_instructions_info`: an array of instruction objects, each containing:\n  - `instructions`: the configured text instructions for AI processing\n  - `scope`: the scope of the instruction — currently only `GLOBAL` is supported\n\n#### Instructions scope\n\n- **GLOBAL**: Instructions that apply globally across the system on the given data-model (currently only global instructions are supported)\n\n#### Error responses\n\n| Code | Description                                                                                                                                                                                        |\n|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                                                                               |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege, lacks view access on the data model, or the bearer token does not correspond to the org where the data model exists. |\n\n> ###### Note:\n>\n> - To use this API, the user needs at least view access on the data model, and must use the bearer token corresponding to the org where the data model exists.\n> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.\n> - Available from version 10.15.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n> - Use this API to review currently configured instructions before modifying them with `setNLInstructions`.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetNLInstructionsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_GetNLInstructionsResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_GetNLInstructionsResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/relevant-questions/:
    post:
      operationId: getRelevantQuestions
      description: "\n<span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 10.13.0.cl or later</span>\n\nBreaks down a natural language query into a series of smaller analytical sub-questions, each mapped to a relevant data source.\n\nRequires `CAN_USE_SPOTTER` privilege and at least view-level access to the referenced metadata objects.\n\n#### Usage guidelines\n\nThe request must include:\n- `query`: the natural language question to decompose into analytical sub-questions\n- `metadata_context`: at least one of the following context identifiers to guide question generation:\n  - `conversation_identifier` — an existing conversation session ID\n  - `answer_identifiers` — a list of Answer GUIDs\n  - `liveboard_identifiers` — a list of Liveboard GUIDs\n  - `data_source_identifiers` — a list of data source GUIDs\n\nOptional parameters for refining the output:\n- `ai_context`: additional context to improve response quality\n  - `content` — supplementary text or CSV data as string input\n  - `instructions` — custom text instructions for the AI system\n- `limit_relevant_questions`: maximum number of questions to return (default: `5`)\n- `bypass_cache`: if `true`, forces fresh computation instead of returning cached results\n\nIf the request is successful, the API returns a list of relevant analytical questions, each containing:\n- `query`: the generated sub-question\n- `data_source_identifier`: the unique ID of the data source the question targets\n- `data_source_name`: the display name of the corresponding data source\n\n#### Error responses\n\n| Code | Description                                                                                                                           |\n|------|---------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                  |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view access to the referenced metadata objects. |\n\n> ###### Note:\n> * This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.\n> * This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRelevantQuestionsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_GetRelevantQuestionsResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_GetRelevantQuestionsResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content:
    get:
      operationId: getSharedContent
      description: "\nReturns the full read-only view of a shared conversation, including ordered\nmessages and data source metadata. Accessible by the conversation owner and\nany principal (user or group) that has been granted access.\nRequires `CAN_USE_SPOTTER` privilege. <br/>  <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nReturns the full read-only view of a shared conversation, including ordered messages and data source metadata. Accessible by the conversation owner and any principal (user or group) that has been granted access via `shareConversation`.\n\nUse this endpoint to render a shared conversation in a UI or to retrieve its content for post-processing. The full answer payload is not embedded in messages — fetch it separately via `loadAnswer` using the `shared_conversation_id` from this response as the `conversation_identifier` parameter, along with the `answer_id` from each `answer` response item.\n\n> **Important**: `shared_conversation_id` is not the same as `conversation_id`. It identifies the shared snapshot, which is a separate internal object from the source conversation. You must use the `shared_conversation_id` value — not `conversation_id` — as the `conversation_identifier` parameter when calling `loadAnswer` to hydrate answers from a shared view.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier` _(query parameter)_: the unique ID of the source conversation.\n\n#### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `conversation_id` | `String` | Echoes the request parameter. |\n| `shared_conversation_id` | `String` | Identifier for the shared snapshot. **This is not the same as `conversation_id`.** Pass this value as the `conversation_identifier` parameter in `loadAnswer` calls. It changes each time the snapshot is refreshed via `shareConversation` with `refresh_shared_content: true` — re-fetch this response to get the current value before calling `loadAnswer`. |\n| `conversation_title` | `String` | Display title of the conversation. `null` if no title was set. |\n| `data_sources` | `DataSourceEntry[]` | Data sources used by the conversation, each with an `id` and display `name`. |\n| `messages` | `ConversationMessage[]` | Ordered conversation messages, oldest to newest. Same structure as returned by `getConversation`. Empty when the conversation has no messages. |\n| `code_execution_files` | `CodeExecutionFileMetadata[]` | Sanitized metadata for files generated by the code-execution tool. Empty when there are none. |\n\n#### DataSourceEntry fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | `String` | Unique identifier of the data source. |\n| `name` | `String` | Display name of the data source. |\n\n#### CodeExecutionFileMetadata fields\n\nEach entry in the `code_execution_files` array contains:\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `file_id` | `String` | Unique identifier of the file. |\n| `display_name` | `String` | Human-readable file name. |\n| `file_type` | `String` | File type such as `csv`, `pdf`, or `png`. |\n| `created_time_in_millis` | `Long` | Milliseconds since Unix epoch when the file was created. |\n| `expired` | `Boolean` | When `true`, the underlying file is no longer retrievable from code-execution storage; UIs should disable download and preview. |\n\n#### Loading answer payloads\n\nEach `answer` response item in `messages[].response_items` contains an `answer_id` field. To retrieve the full answer payload (TML tokens, visualization metadata, chart config), call `loadAnswer` with:\n\n- `conversation_identifier`: the `shared_conversation_id` from **this** response (not `conversation_id`)\n- `answer_identifier`: the `answer_id` from the `answer` item\n\nIf the snapshot has been refreshed since you last called `getSharedContent`, the `shared_conversation_id` will have changed. Always use the `shared_conversation_id` from the most recent `getSharedContent` response; stale values return 404.\n\n#### Example request\n\n```bash\nGET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content\n```\n\n#### Example response\n\n```json\n{\n  \"conversation_id\": \"conv-abc-123\",\n  \"shared_conversation_id\": \"snap-xyz-456\",\n  \"conversation_title\": \"Sales by Region Q1\",\n  \"data_sources\": [{ \"id\": \"ds-001\", \"name\": \"Retail Sales\" }],\n  \"messages\": [\n    {\n      \"message_id\": \"node-u-01\",\n      \"timestamp_in_millis\": 1744000000000,\n      \"user_prompt\": {\n        \"message\": {\n          \"message_id\": \"msg-u-01\",\n          \"content\": \"Show me revenue by region.\"\n        },\n        \"attachments\": []\n      },\n      \"response_items\": [\n        {\n          \"type\": \"tool_call\",\n          \"tool_call_id\": \"toolu-01\",\n          \"tool_name\": \"search_datasets\",\n          \"step_title\": \"Searching datasets\",\n          \"arguments\": { \"query\": \"revenue by region\" },\n          \"timestamp_in_millis\": 1744000001000,\n          \"is_thinking\": false\n        },\n        {\n          \"type\": \"answer\",\n          \"answer_id\": \"ans-01\",\n          \"tool_call_id\": \"toolu-02\",\n          \"tool_name\": \"fetch_and_visualize\",\n          \"step_title\": \"Visualizing\",\n          \"timestamp_in_millis\": 1744000004000,\n          \"is_thinking\": false\n        },\n        {\n          \"type\": \"text\",\n          \"content\": \"Revenue is highest in APAC.\",\n          \"content_type\": \"TEXT_MARKDOWN\",\n          \"timestamp_in_millis\": 1744000005000,\n          \"is_thinking\": false,\n          \"step_title\": null,\n          \"file_reference\": null\n        }\n      ]\n    }\n  ],\n  \"code_execution_files\": [\n    {\n      \"file_id\": \"revenue_by_region.csv\",\n      \"display_name\": \"revenue_by_region.csv\",\n      \"file_type\": \"csv\",\n      \"created_time_in_millis\": 1744027200000,\n      \"expired\": false\n    }\n  ]\n}\n```\n\nFor the `ConversationMessage` field structure, see `getConversation`.\n\n#### Error responses\n\n| Code | Description |\n| --- | --- |\n| 401 | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403 | Forbidden — the caller is neither the conversation owner nor a principal with access, or does not have `CAN_USE_SPOTTER` privilege. |\n| 404 | Not Found — no active shared view exists for the given conversation identifier. |\n\n> ###### Note:\n>\n> - The shared view is a point-in-time copy of the conversation. It may not reflect edits made after sharing. Check `is_shared_content_outdated` via `getShareInfo` and use `shareConversation` with `refresh_shared_content: true` to update.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n<span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the source conversation.
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedConversationResponse'
              examples:
                example_1:
                  summary: Shared conversation with one message and an answer
                  value:
                    conversation_id: conv-abc-123
                    shared_conversation_id: snap-xyz-456
                    conversation_title: Sales by Region Q1
                    data_sources:
                    - id: ds-001
                      name: Retail Sales
                    messages:
                    - message_id: node-u-01
                      timestamp_in_millis: 1744000000000
                      user_prompt:
                        message:
                          message_id: msg-u-01
                          content: Show me revenue by region.
                        attachments: []
                      response_items:
                      - type: answer
                        answer_id: ans-01
                        tool_call_id: toolu-01
                        tool_name: fetch_and_visualize
                        step_title: Visualizing
                        timestamp_in_millis: 1744000004000
                        is_thinking: false
                      - type: text
                        content: Revenue is highest in APAC at $4.2M.
                        content_type: TEXT_MARKDOWN
                        timestamp_in_millis: 1744000005000
                        is_thinking: false
                        step_title: null
                        file_reference: null
                    code_execution_files:
                    - file_id: revenue_by_region.csv
                      display_name: revenue_by_region.csv
                      file_type: csv
                      created_time_in_millis: 1744027200000
                      expired: false
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedConversationResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info:
    get:
      operationId: getShareInfo
      description: "\nReturns the current share state for a conversation the caller owns: whether\nthe shared view is outdated relative to the latest conversation content, and\nthe list of principals that currently have access.\nRequires `CAN_USE_SPOTTER` privilege and ownership of the specified conversation. <br/>  <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nReturns the current share state for a conversation the caller owns: whether the shared view reflects the latest conversation content, and the list of principals that currently have access.\n\nUse this endpoint to render a share management UI, audit who has access to a conversation, or determine whether the shared view needs to be refreshed before sending a link.\n\nRequires ownership of the specified conversation.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier` _(query parameter)_: the unique ID of the conversation, as returned by `createAgentConversation` or `getConversationList`.\n\n#### Response fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `conversation_id` | `String` | Echoes the request parameter. |\n| `is_shared_content_outdated` | `Boolean` | `true` when the shared view was generated before the last edit to the conversation and does not reflect the latest content. `false` when the shared view is current. `null` when the conversation has never been shared. |\n| `principals` | `ConversationPrincipalInfo[]` | List of principals with access. Empty when no access has been granted. The conversation owner is never included. |\n\n#### ConversationPrincipalInfo fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | `String` | Unique identifier of the user or group. |\n| `type` | `Principals` | `USER` for individual users, `USER_GROUP` for groups. |\n| `display_name` | `String` | Display name as shown in the ThoughtSpot UI. |\n| `name` | `String` | Internal name of the user or group. |\n| `permission` | `String` | Access level. Always `READ_ONLY` for shared conversations. |\n\n#### Example request\n\n```bash\nGET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info\n```\n\n#### Example response — conversation shared and current\n\n```json\n{\n  \"conversation_id\": \"conv-abc-123\",\n  \"is_shared_content_outdated\": false,\n  \"principals\": [\n    {\n      \"id\": \"user-001\",\n      \"type\": \"USER\",\n      \"display_name\": \"Alice Example\",\n      \"name\": \"alice.example\",\n      \"permission\": \"READ_ONLY\"\n    },\n    {\n      \"id\": \"group-001\",\n      \"type\": \"USER_GROUP\",\n      \"display_name\": \"Sales Team\",\n      \"name\": \"sales-team\",\n      \"permission\": \"READ_ONLY\"\n    }\n  ]\n}\n```\n\n#### Example response — conversation never shared\n\n```json\n{\n  \"conversation_id\": \"conv-abc-123\",\n  \"is_shared_content_outdated\": null,\n  \"principals\": []\n}\n```\n\n#### Example response — shared view outdated\n\n```json\n{\n  \"conversation_id\": \"conv-abc-123\",\n  \"is_shared_content_outdated\": true,\n  \"principals\": [\n    {\n      \"id\": \"user-001\",\n      \"type\": \"USER\",\n      \"display_name\": \"Alice Example\",\n      \"name\": \"alice.example\",\n      \"permission\": \"READ_ONLY\"\n    }\n  ]\n}\n```\n\nWhen `is_shared_content_outdated` is `true`, call `shareConversation` with `refresh_shared_content: true` to update the shared view with the latest conversation content.\n\n#### Error responses\n\n| Code | Description |\n| --- | --- |\n| 401 | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403 | Forbidden — the caller does not own the specified conversation, or does not have `CAN_USE_SPOTTER` privilege. |\n| 404 | Not Found — no conversation exists with the given identifier for the authenticated user. |\n\n> ###### Note:\n>\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n<span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation.
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationShareStatusResponse'
              examples:
                example_1:
                  summary: Conversation shared with two principals, content is current
                  value:
                    conversation_id: conv-abc-123
                    is_shared_content_outdated: false
                    principals:
                    - id: user-001
                      type: USER
                      display_name: Alice Example
                      name: alice.example
                      permission: READ_ONLY
                    - id: group-001
                      type: USER_GROUP
                      display_name: Sales Team
                      name: sales-team
                      permission: READ_ONLY
                example_2:
                  summary: Conversation never shared
                  value:
                    conversation_id: conv-abc-123
                    is_shared_content_outdated: null
                    principals: []
                example_3:
                  summary: Shared view is outdated — conversation was edited after sharing
                  value:
                    conversation_id: conv-abc-123
                    is_shared_content_outdated: true
                    principals:
                    - id: user-001
                      type: USER
                      display_name: Alice Example
                      name: alice.example
                      permission: READ_ONLY
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationShareStatusResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/memory/import:
    post:
      operationId: importMemory
      description: "\nImports memory entries (rules, recipes, and always-apply rules) from\na YAML payload, typically a payload produced by `exportMemory` and\nedited locally. The imported entries replace the existing memory for\nthe data-models referenced in the payload.\n`dry_run` is required. Pass `true` first to validate the payload and\nreview the preview counts and any row-level failures without making\nchanges, then re-run with `dry_run = false` to apply the import. An\nimport is not applied if any row fails validation.\nRequires Spotter access (use/manage) and either edit or memory\naccess on corresponding data model sources. <br/> <span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 26.8.0.cl or later</span>\n\nThis API allows users to import data-model memories using a given yaml file. This yaml file can be obtained from the export memory API in source env and can be modified and used as input to the import API in target env.\n\nThis API enables customers to migrate memories from a source env to a target env. This improves memory adoption for Spotter by giving the users a chance to develop their memories in one env and replicate the same in another env.\n\n#### Usage guidelines\n\nTo import memory, the request must include:\n- `content`: The full serialized memory payload to import (YAML). Typically the `content` value returned by the `exportMemory` API, edited locally and re-submitted. The payload itself identifies which data-models the memory applies to, so no separate identifier list is required.\n- `dry_run`: Required. When `true`, validate the payload and return preview counts without writing anything; when `false`, apply the import. Always run with `dry_run = true` first, then re-run with `dry_run = false` once you are satisfied with the preview.\n\nThe import replaces the existing global memories on the data-models referenced in the payload with the entries supplied in the payload.\n\nThe API returns a response object with:\n- `status`: The terminal status of the import (`SUCCESS`, `VALIDATION_FAILED`, or `FAILED`).\n- `summary`: Per `(memory_type, source)` counts. In a dry run the `deleted_record_count`/`inserted_record_count` are previews; in a real import they are actuals. On `VALIDATION_FAILED`, `summary` is `null` when validation fails before any item is processed (e.g. an unresolved or inaccessible data-model source) and an empty list otherwise — treat both as \"no counts available\".\n- `validation_failures`: Per-item validation failures, each with `line_number`, `reason`, `field_name`, and `message` for click-to-locate and inline highlighting.\n- `diagnostics`: Groups of diagnostic messages, each with a `sub_status` (`WARNING`, `FAILURE`, `ROLLED_BACK`, or `UNKNOWN`) and a `messages` list. This is the single channel for both non-fatal warnings (under `WARNING`, e.g. when some older memory entries could not be fully cleaned up) and fatal causes (e.g. the failure reason under `FAILURE`, or a `ROLLED_BACK` group when new entries were undone).\n- `operation_id`: A server-generated identifier for this import operation; include it when contacting support to help correlate server-side logs. Populated once the server registers the import operation; `null` when the request fails earlier (e.g. while parsing the payload or resolving its data-model sources).\n\n#### File format\n\nThe payload is a YAML document with a single top-level `memories` key holding a list of memory items. Each item is self-contained: a `type`, a typed `content` block, a `datamodel_sources` list, and optional `tags`. Typically you don't hand-author this file — you obtain it from `exportMemory`, edit it, and submit it back through `importMemory`.\n\n```yaml\nmemories:\n- type: RULE\n  content:\n    rule_definition: \"Always filter revenue to closed-won deals.\"\n  datamodel_sources:\n  - guid: 11111111-1111-1111-1111-111111111111\n    obj_id: sales_data_model\n  tags:\n  - finance\n- type: RULE\n  content:\n    rule_definition: \"Exclude internal test accounts from all results.\"\n  datamodel_sources:\n  - obj_id: sales_data_model\n- type: RECIPE\n  content:\n    user_query: \"top accounts by revenue\"\n    recipe: |\n      {\"steps\": [...serialized recipe blob...]}\n  datamodel_sources:\n  - obj_id: sales_data_model\n- type: RECIPE\n  content:\n    user_query: \"monthly new customer count\"\n    recipe: |\n      {\"steps\": [...serialized recipe blob...]}\n  datamodel_sources:\n  - obj_id: sales_data_model\n- type: ALWAYS_APPLY_RULES\n  content:\n    rules:\n    - \"Never show internal test accounts.\"\n    - \"Round currency to whole dollars.\"\n  datamodel_sources:\n  - guid: 22222222-2222-2222-2222-222222222222\n```\n\nA file can contain multiple `RULE` and multiple `RECIPE` items for a data-model, but at most one `ALWAYS_APPLY_RULES` item per data-model.\n\n##### Memory item fields\n\n| Field | Required | Type | Description |\n|-------|----------|------|-------------|\n| `type` | Yes | String enum | One of `RULE`, `RECIPE`, or `ALWAYS_APPLY_RULES`. |\n| `content` | Yes | Mapping | Type-specific content block (see below). |\n| `datamodel_sources` | Yes | Non-empty list | The data-model(s) the memory attaches to. |\n| `tags` | No | List of strings | Free-form labels. |\n\n##### Memory types and content\n\n| `type` | Content fields | Notes |\n|--------|----------------|-------|\n| `RULE` | `rule_definition` — required, non-empty string | A single semantic rule. |\n| `RECIPE` | `recipe` and `user_query` — both required, non-empty strings | `recipe` is an opaque serialized blob; `user_query` is the natural-language query it answers. |\n| `ALWAYS_APPLY_RULES` | `rules` — required, non-empty list of non-empty strings | Data-model-wide always-apply rules. At most one `ALWAYS_APPLY_RULES` item per data-model. |\n\n##### Identifying data-models (`datamodel_sources`)\n\nEach item must list at least one source. Each entry identifies a data-model by at least one of:\n- `guid` — the data-model GUID.\n- `obj_id` — a stable object ID, resolved to a GUID server-side.\n\nIf both are supplied, `obj_id` takes precedence and `guid` is ignored entirely; `guid` takes effect only when `obj_id` is absent. Exported files populate `guid` and, if present, `obj_id` as well.\n\n> ⚠️ **Cross-environment import:** When `obj_id` is present it is\n> authoritative — the accompanying `guid` is **not** used as a fallback.\n> If an `obj_id` does not exist in the target environment, that item\n> fails with `UNRESOLVED_SOURCE`. Remove or correct stale `obj_id`\n> values before importing across environments.\n\n#### Validations reference\n\nThe payload is fully validated before anything is written. This applies to `dry_run = true` and `dry_run = false` alike: if any item fails validation, the entire import is rejected — no partial writes — and all failures are returned together so you can fix them in one pass.\n\n##### Limits\n\nDefault limits (may be adjusted in future if the need arises):\n\n| Limit | Default |\n|-------|---------|\n| Uploaded file size | 10 MiB |\n| Total memory items | 10,000 |\n| `rule_definition` length | 1,000 characters |\n| `user_query` length | 1,000 characters |\n| `recipe` length | 2,000 characters |\n| `rules` combined length (`ALWAYS_APPLY_RULES`) | 2,000 characters |\n| Tags per item | 10 |\n| Characters per tag | 50 |\n\nThe `rules` limit in `ALWAYS_APPLY_RULES` is a combined budget across all entries in the list, not per entry.\n\n##### Structural rules\n\n- The document must be a mapping with a `memories` key whose value is a list.\n- Unknown keys — at the top level, within an item, or under `content` — are rejected.\n- Each item's `type` must be one of the three supported values, and `content` must match that type's shape.\n- Null, empty-string, or wrong-typed values in a required field are treated as missing.\n- Non-string or empty `tags` entries are dropped silently; certain tags reserved for internal use are stripped automatically before the item is stored.\n\n##### Cross-item rules\n\n- A data-model referenced by more than one `ALWAYS_APPLY_RULES` item is rejected — combine them into a single item's `rules` list.\n\n##### Failure reasons\n\nEach entry in `validation_failures` carries one of:\n\n| Reason | Meaning |\n|--------|---------|\n| `SCHEMA` | YAML structure is invalid or unsupported. |\n| `VALIDATION` | A required field is missing/empty, a count exceeds a limit, or a GUID is malformed. |\n| `CHAR_LIMIT` | A content field or tag exceeds its size limit. |\n| `UNRESOLVED_SOURCE` | A `guid` or `obj_id` could not be resolved to an existing data-model. |\n| `ACCESS_DENIED` | The caller lacks sufficient access on the referenced data-model. |\n\n#### Dry run\n\n`dry_run` is required and has no default, so the import is always a deliberate two-step flow:\n\n1. **First, call with `dry_run = true`.** This validates the payload and previews what would happen — the counts in `summary` and any `validation_failures` — without writing anything.\n2. **Then, after reviewing a clean preview, call again with `dry_run = false`** (same `content`). This applies the import. It refuses to write when any item fails validation, so fix the reported `validation_failures` and resubmit.\n\n> ###### Important:\n> Never call `dry_run = false` without first inspecting a `dry_run = true` preview. A real import deletes and replaces existing global memories on the referenced data-models.\n\n#### Error responses\n\n| Code | Description                                                                                                                                                                                  |\n|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                                                                        |\n| 403  | Forbidden — the authenticated user does not have the necessary Spotter permissions, or the bearer token does not correspond to the data-model's org. Per-data-model access failures do not use this code — they surface as `ACCESS_DENIED` validation failures with HTTP `200` (see Logical failures below). |\n\n#### Logical failures\n\nValidation and write failures are not returned in the error envelope. The call returns `200` with a terminal `status` of `VALIDATION_FAILED` or `FAILED`, and the details live in `validation_failures` / `diagnostics`:\n\n- **VALIDATION_FAILED** — one or more items failed schema/semantic validation; nothing was written. Inspect `validation_failures`, fix the items, and resubmit.\n- **FAILED** — the import did not complete. Inspect `diagnostics`: a `ROLLED_BACK` group means writing the new entries failed and any entries written before the failure were undone (existing memory is intact, no destructive change), while a `FAILURE` group carries another non-validation cause.\n\nSample `VALIDATION_FAILED` responses (HTTP 200):\n\n**Invalid data-model (unresolved source):**\n\n```json\n{\n    \"status\": \"VALIDATION_FAILED\",\n    \"summary\": null,\n    \"validation_failures\": [\n        {\n            \"line_number\": 2,\n            \"reason\": \"UNRESOLVED_SOURCE\",\n            \"field_name\": \"datamodel_sources[0].guid\",\n            \"message\": \"unknown datamodel guid: 55555555-5555-5555-5555-555555555555\"\n        }\n    ],\n    \"diagnostics\": [\n        {\n            \"sub_status\": \"FAILURE\",\n            \"messages\": [\n                \"unknown datamodel guid: 55555555-5555-5555-5555-555555555555\"\n            ]\n        }\n    ],\n    \"operation_id\": null\n}\n```\n\n**Inaccessible data-models:**\n\n```json\n{\n    \"status\": \"VALIDATION_FAILED\",\n    \"summary\": null,\n    \"validation_failures\": [\n        {\n            \"line_number\": 2,\n            \"reason\": \"ACCESS_DENIED\",\n            \"field_name\": \"datamodel_sources[0]\",\n            \"message\": \"Insufficient permissions on datamodel '44444444-4444-4444-4444-444444444444'\"\n        },\n        {\n            \"line_number\": 8,\n            \"reason\": \"ACCESS_DENIED\",\n            \"field_name\": \"datamodel_sources[0]\",\n            \"message\": \"Insufficient permissions on datamodel '33333333-3333-3333-3333-333333333333'\"\n        }\n    ],\n    \"diagnostics\": [\n        {\n            \"sub_status\": \"FAILURE\",\n            \"messages\": [\n                \"Memory import validation failed with 2 error(s): Insufficient permissions on datamodel '44444444-4444-4444-4444-444444444444'; Insufficient permissions on datamodel '33333333-3333-3333-3333-333333333333'\"\n            ]\n        }\n    ],\n    \"operation_id\": null\n}\n```\n\n**Character-limit validations:**\n\n```json\n{\n    \"status\": \"VALIDATION_FAILED\",\n    \"summary\": [],\n    \"validation_failures\": [\n        {\n            \"line_number\": 3,\n            \"reason\": \"CHAR_LIMIT\",\n            \"field_name\": \"content.rule_definition\",\n            \"message\": \"content.rule_definition is 1073 characters; max allowed is 1000\"\n        },\n        {\n            \"line_number\": 49,\n            \"reason\": \"CHAR_LIMIT\",\n            \"field_name\": \"content.user_query\",\n            \"message\": \"content.user_query is 1150 characters; max allowed is 1000\"\n        },\n        {\n            \"line_number\": 49,\n            \"reason\": \"CHAR_LIMIT\",\n            \"field_name\": \"content.recipe\",\n            \"message\": \"content.recipe is 3574 characters; max allowed is 2000\"\n        }\n    ],\n    \"diagnostics\": [\n        {\n            \"sub_status\": \"FAILURE\",\n            \"messages\": [\n                \"Validation failures present; fix them and re-run to see the DRY_RUN preview.\"\n            ]\n        }\n    ],\n    \"operation_id\": \"66666666-6666-6666-6666-666666666666\"\n}\n```\n\n> ###### Note:\n> - To use this API, the user needs Spotter access (use/manage) and either edit or memory access on the data-model and they must use corresponding org related bearerToken where the data-model exists.\n> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.\n> - Available from version 26.8.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportMemoryRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportMemoryResponse'
              examples:
                example_1:
                  summary: Successful dry-run preview
                  value:
                    status: SUCCESS
                    summary:
                    - memory_type: RULES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 3
                      deleted_record_count: 3
                      inserted_record_count: 2
                      failed_record_count: 0
                    - memory_type: RECIPES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 7
                      deleted_record_count: 7
                      inserted_record_count: 4
                      failed_record_count: 0
                    - memory_type: ALWAYS_APPLY_RULES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 0
                      deleted_record_count: 0
                      inserted_record_count: 1
                      failed_record_count: 0
                    validation_failures: []
                    diagnostics: []
                    operation_id: 77777777-7777-7777-7777-777777777777
                example_2:
                  summary: Successful import (dry_run=false)
                  value:
                    status: SUCCESS
                    summary:
                    - memory_type: RULES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 3
                      deleted_record_count: 3
                      inserted_record_count: 2
                      failed_record_count: 0
                    - memory_type: RECIPES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 7
                      deleted_record_count: 7
                      inserted_record_count: 4
                      failed_record_count: 0
                    - memory_type: ALWAYS_APPLY_RULES
                      source:
                        identifier: 33333333-3333-3333-3333-333333333333
                        type: DATA_MODEL
                      existing_record_count: 0
                      deleted_record_count: 0
                      inserted_record_count: 1
                      failed_record_count: 0
                    validation_failures: []
                    diagnostics: []
                    operation_id: 88888888-8888-8888-8888-888888888888
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportMemoryResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details:
    get:
      operationId: loadAnswer
      description: "\nLoads the full answer payload for a specific answer item in an agent\nconversation. Returns structured answer data including the TML query, token\nbreakdown, visualization metadata, and agent context state.\nPass the `answer_id` from an `AnswerResponseItem` in the `getConversation`\nresponse as the `answer_identifier` parameter.\nRequires `CAN_USE_SPOTTER` privilege and access to the specified conversation. <br/>  <span class=\"since-beta-tag\">Version: 26.7.0.cl or later</span>\n\nLoads the answer details for a specific answer item in an agent conversation. Returns structured answer data including the TML token list, visualization metadata, and agent context state. Use this endpoint to retrieve the full answer representation for an answer item — for example, to re-render a chart, export a query, or inspect the generated TML.\n\nRequires `CAN_USE_SPOTTER` privilege and access to the specified conversation.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier` *(path parameter)*: the unique ID of the conversation, as returned by `createAgentConversation`\n- `answer_identifier` *(path parameter)*: the `answer_id` field from an `AnswerResponseItem` in the `getConversation` response\n\nIf the request is successful, the response contains an `answer` object with the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | `String` | Display title of the generated answer (e.g., `\"sales by month\"`). |\n| `description` | `String` | Optional description of the answer. |\n| `session_identifier` | `String` | Unique identifier of the session in which this answer was generated. |\n| `generation_number` | `Int` | Generation sequence number of this answer within the session. |\n| `tokens` | `[String]` | Ordered list of TML token strings that make up the answer query (e.g., `[\"[sales]\", \"[date].'monthly'\"]`). |\n| `visualization_type` | `VizType` | Suggested visualization type: `Chart`, `Table`, or `Undefined`. `null` if no suggestion is available. |\n| `formulas` | `[String]` | List of formula names referenced in the answer. Empty if none are used. |\n| `parameters` | `[String]` | List of parameter names applied to the answer. Empty if none are used. |\n| `sub_queries` | `[JSON]` | List of sub-query objects used in the answer. Empty if none are present. |\n| `ac_state` | `ACState` | Agent context state, including `transaction_identifier` and `generation_number`, used to correlate this answer with a specific agent turn. |\n\n#### ACState fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `transaction_identifier` | `String` | Unique identifier of the agent transaction that produced this answer. |\n| `generation_number` | `Int` | Generation number within the transaction. |\n\n#### Example request\n\n```bash\nGET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details\n```\n\n#### Example response\n\n```json\n{\n  \"answer\": {\n    \"title\": \"sales by month\",\n    \"description\": \"\",\n    \"session_identifier\": \"7b00b801-73f4-4639-af5e-e775584ceba6\",\n    \"generation_number\": 1,\n    \"tokens\": [\"[sales]\", \"[date].'monthly'\"],\n    \"visualization_type\": null,\n    \"formulas\": [],\n    \"parameters\": [],\n    \"sub_queries\": [],\n    \"ac_state\": {\n      \"transaction_identifier\": \"7f6c9948-b4c7-4098-bb1f-6c67bc0e5699\",\n      \"generation_number\": 1\n    }\n  }\n}\n```\n\n#### Typical usage scenario\n\n1. Call `getConversation` to retrieve the full conversation history.\n2. Locate an `AnswerResponseItem` in `response_items` — note its `answer_id` field.\n3. Call `loadAnswer` with the `conversation_identifier` and `answer_id` as `answer_identifier`.\n4. The returned `tokens` array can be used to open the answer in the ThoughtSpot search interface or rendered as pill chips in the UI.\n\n#### Error responses\n\n| Code | Description |\n|------|-------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks access to the specified conversation. |\n| 404  | Not Found — no conversation or message exists with the given identifiers for the authenticated user. |\n| 422  | Unprocessable Entity — the message does not contain an answer of the expected type. |\n\n> ###### Note:\n>\n> - This endpoint only loads answer-type messages. Other message types are not supported.\n> - `visualization_type` may be `null` if the agent did not produce a visualization suggestion for this answer.\n> - `formulas`, `parameters`, and `sub_queries` are returned as empty arrays when not applicable — they are never `null`.\n> - Available from version 26.7.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation.
      - in: path
        name: answer_identifier
        required: true
        schema:
          type: string
        description: 'Unique identifier of the answer to load. Use the `answer_id` field from an

          `AnswerResponseItem` returned by `getConversation`.'
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadAnswerResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadAnswerResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/analytical-questions:
    post:
      operationId: queryGetDecomposedQuery
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.7.0.cl or later</span>


        <span class="since-beta-tag">Version: 10.7.0.cl or later</span>


        **Deprecated** — Use `getRelevantQuestions` instead (available from 10.13.0.cl).


        Breaks down a topical or goal-oriented natural language question into smaller, actionable analytical sub-questions, each mapped to a relevant data source for independent execution.


        Requires `CAN_USE_SPOTTER` privilege and at least view-level access to the referenced metadata objects.


        #### Usage guidelines


        The request accepts the following parameters:


        - `nlsRequest`: contains the user `query` to decompose, along with optional `instructions` and `bypassCache` flag

        - `worksheetIds`: list of data source identifiers to scope the decomposition

        - `answerIds`: list of Answer GUIDs whose data guides the response

        - `liveboardIds`: list of Liveboard GUIDs whose data guides the response

        - `conversationId`: an existing conversation session ID for context continuity

        - `content`: supplementary text or CSV data to improve response quality

        - `maxDecomposedQueries`: maximum number of sub-questions to return (default: `5`)


        If the request is successful, the API returns a `decomposedQueryResponse` containing a list of `decomposedQueries`, each with:

        - `query`: the generated analytical sub-question

        - `worksheetId`: the unique ID of the data source the question targets

        - `worksheetName`: the display name of the corresponding data source


        #### Error responses


        | Code | Description                                                                                                                           |

        |------|---------------------------------------------------------------------------------------------------------------------------------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                  |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view access to the referenced metadata objects. |


        > ###### Note:

        > * This endpoint is deprecated since 10.13.0.cl. Use `getRelevantQuestions` for new integrations.

        > * This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > * This endpoint requires Spotter — please contact ThoughtSpot support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      deprecated: true
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryGetDecomposedQueryRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_DecomposeQueryResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_DecomposeQueryResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send:
    post:
      operationId: sendAgentConversationMessage
      description: "\n <span class=\"since-beta-tag\">Version: 26.5.0.cl or later</span>\n\n<span class=\"since-beta-tag\">Version: 26.5.0.cl or later</span>\n\nSends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously.\n\nRequires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`. A conversation must first be created using the `createAgentConversation` API.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking\n- `messages`: an array of one or more text messages to send to the agent\n\nThe API returns an array of response objects, each containing:\n\n- `type`: the kind of response — `text`, `answer`, or `error`\n- `message`: the main content of the response\n- `metadata`: additional information depending on the message type (e.g., answer metadata includes analytics and visualization details)\n\n#### Error responses\n\n| Code | Description                                                                                                                      |\n|------|----------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                             |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |\n\n> ###### Note:\n>\n> - This endpoint is Generally Available from version 26.5.0.cl.\n> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.\n> - For real-time streamed responses, use `sendAgentConversationMessageStreaming` instead.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendAgentConversationMessageRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier for the conversation (used to track context)
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                type: object
              examples:
                example_1:
                  summary: Send a message to an existing agent conversation
                  value:
                    messages:
                    - metadata: {}
                      internal: {}
                      type: text
                      text: '


                        I''ll compare sales between 2025 and 2024. First, let me get the dataset context to identify the relevant sales and date columns.'
                      agent_context: ''
                    - metadata: {}
                      internal: {}
                      type: text
                      text: '```json

                        {"search_mode": "semantic", "dataset_name": "(Sample) Retail - Apparel", "columns": [{"name": "sales", "type": "MEASURE", "data_type": "double"}, {"name": "date", "type": "ATTRIBUTE", "data_type": "date", "sample_values": ["2025", "2024"]}]}

                        ```'
                      agent_context: ''
                    - metadata: {}
                      internal: {}
                      type: text
                      text: '


                        Perfect! I found the sales and date columns. I can see the dataset contains sales data for both 2025 and 2024. Now I''ll create a comparison query to show sales for 2025 versus 2024.'
                      agent_context: ''
                    - metadata:
                        output: <base64-encoded-protobuf-output>
                        worksheet_id: cd252e5c-b552-49a8-821d-3eadaa049cca
                        assumptions: ''
                        chart_type: KPI
                        interrupted: false
                        data_awareness_enabled: true
                      internal: {}
                      type: answer
                      title: Compare total sales for 2025 vs 2024
                      description: ''
                      session_id: 842bb67a-e08e-4861-97e8-8db9538db51d
                      gen_no: 2
                      sage_query: '[sales] [date] = ''2025'' vs [date] = ''2024'''
                      tml_tokens:
                      - '[sales]'
                      - '[date] = ''2025'' vs [date] = ''2024'''
                      formulas: []
                      parameters: []
                      subqueries: []
                      viz_suggestion: CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA
                      ac_state: null
                    - metadata: {}
                      internal: {}
                      type: text
                      text: '


                        The visualization shows the side-by-side comparison of total sales (in USD) between the two years, allowing you to see the year-over-year performance. You can see the sales figures for both 2024 and 2025, making it easy to identify growth or decline trends in your retail apparel business.'
                      agent_context: ''
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream:
    post:
      operationId: sendAgentConversationMessageStreaming
      description: "\n <span class=\"since-beta-tag\">Version: 26.5.0.cl or later</span>\n\n<span class=\"since-beta-tag\">Version: 26.5.0.cl or later</span>\n\nSends one or more natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events stream.\n\nRequires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`. A conversation must first be created using the `createAgentConversation` API.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking\n- `messages`: an array of one or more text messages to send to the agent\n\nIf the request is valid, the API returns a Server-Sent Events (SSE) stream. Each line has the form `data: [{\"type\": \"...\", ...}]` — a JSON array of event objects. Event types include:\n\n- `ack`: confirms receipt of the request (`node_id`)\n- `conv_title`: conversation title (`title`, `conv_id`)\n- `notification`: status updates on operations (`group_id`, `metadata`, `code` — e.g. `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`)\n- `text-chunk`: incremental content chunks (`id`, `group_id`, `metadata` with `format` and `type` such as `thinking` or `text`, `content`)\n- `text`: full text block with same structure as `text-chunk`\n- `answer`: structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title`, etc., `title`)\n- `error`: if a failure occurs\n\n#### Error responses\n\n| Code | Description                                                                                                                      |\n| ---- | -------------------------------------------------------------------------------------------------------------------------------- |\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                             |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |\n\n> ###### Note:\n>\n> - This endpoint is Generally Available from version 26.5.0.cl.\n> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.\n> - The streaming protocol uses Server-Sent Events (SSE).\n> - For the complete response in a single payload, use `sendAgentConversationMessage` instead.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendAgentConversationMessageStreamingRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier for the conversation (used to track context)
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendAgentMessageResponse'
              examples:
                example_1:
                  summary: 'SSE stream — each line is data: [{"type": "...", ...}]. Events arrive over time; this example shows a minimal sequence.'
                  value:
                  - type: ack
                    node_id: aGxzcFVrtom8
                  - type: conv_title
                    title: Sales 2025 vs 2024
                    conv_id: -XIi04l5rrof
                  - type: notification
                    group_id: cDEsAQbSnd3J
                    metadata:
                      type: thinking
                      tool_title: 'Analyzing Sales Performance: 2025 vs 2024'
                    code: TOOL_CALL_NOTIFICATION
                  - id: mNAdvy-NK2l6
                    type: text-chunk
                    group_id: cDEsAQbSnd3J
                    metadata:
                      format: markdown
                      type: thinking
                    content: '


                      I need to compare sales performance between 2025 and 2024.'
                  - id: hxWMDP-pgR3B
                    type: answer
                    group_id: m1MTvttEUa7o
                    metadata:
                      sage_query: '[sales] [date] = ''2025'' vs [date] = ''2024'''
                      session_id: 431adcf9-1328-4d8c-81a1-0faa7fa37ba6
                      title: Compare sales for 2025 vs 2024
                    title: Compare sales for 2025 vs 2024
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendAgentMessageResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-streaming: true
  /api/rest/2.0/ai/agent/{conversation_identifier}/converse:
    post:
      operationId: sendAgentMessage
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.2.0.cl or later</span>


        **Deprecated** — Use `sendAgentConversationMessage` instead.


        Send natural language messages to an existing Spotter agent conversation and returns the complete response synchronously.


        Requires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`.

        A conversation must first be created using the `createAgentConversation` API.


        #### Usage guidelines


        The request must include:


        - `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking

        - `messages`: an array of one or more text messages to send to the agent


        The API returns an array of response objects, each containing:


        - `type`: the kind of response — `text`, `answer`, or `error`

        - `message`: the main content of the response

        - `metadata`: additional information depending on the message type (e.g., answer metadata includes analytics and visualization details)


        #### Error responses


        | Code | Description                                                                                                                      |

        |------|----------------------------------------------------------------------------------------------------------------------------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                             |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |


        > ###### Note:

        >

        > - This endpoint is deprecated. Use `sendAgentConversationMessage` for new integrations.

        > - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      deprecated: true
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendAgentMessageRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier for the conversation (used to track context)
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                type: object
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/converse/sse:
    post:
      operationId: sendAgentMessageStreaming
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.2.0.cl or later</span>


        **Deprecated** — Use `sendAgentConversationMessageStreaming` instead.


        Sends one or more natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events stream.


        Requires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`. A conversation must first be created using the `createAgentConversation` API.


        #### Usage guidelines


        The request must include:


        - `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking

        - `messages`: an array of one or more text messages to send to the agent


        If the request is valid, the API returns a Server-Sent Events (SSE) stream. Each line has the form `data: [{"type": "...", ...}]` — a JSON array of event objects. Event types include:


        - `ack`: confirms receipt of the request (`node_id`)

        - `conv_title`: conversation title (`title`, `conv_id`)

        - `notification`: status updates on operations (`group_id`, `metadata`, `code` — e.g. `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`)

        - `text-chunk`: incremental content chunks (`id`, `group_id`, `metadata` with `format` and `type` such as `thinking` or `text`, `content`)

        - `text`: full text block with same structure as `text-chunk`

        - `answer`: structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title`, etc., `title`)

        - `error`: if a failure occurs


        #### Error responses


        | Code | Description                                                                                                                      |

        |------|----------------------------------------------------------------------------------------------------------------------------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                             |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |


        > ###### Note:

        >

        > - This endpoint is deprecated. Use `sendAgentConversationMessageStreaming` for new integrations.

        > - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.

        > - The streaming protocol uses Server-Sent Events (SSE).





        #### Endpoint URL

        '
      deprecated: true
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendAgentMessageStreamingRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendAgentMessageResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendAgentMessageResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-streaming: true
  /api/rest/2.0/ai/conversation/{conversation_identifier}/converse:
    post:
      operationId: sendMessage
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>


        Sends a follow-up message to an existing conversation within the context of a data model.


        Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request. A conversation must first be created using the `createConversation` API.


        #### Usage guidelines


        The request must include:

        - `conversation_identifier`: the unique session ID returned by `createConversation`

        - `metadata_identifier`: the unique ID of the data source used for the conversation

        - `message`: a natural language string with the follow-up question


        If the request is successful, the API returns an array of response messages, each containing:

        - `session_identifier`: the unique ID of the generated response

        - `generation_number`: the generation number of the response

        - `message_type`: the type of the response (e.g., `TSAnswer`)

        - `visualization_type`: the generated visualization type (`Chart`, `Table`, or `Undefined`)

        - `tokens` / `display_tokens`: the search tokens and user-friendly display tokens for the response


        #### Error responses


        | Code | Description                                                                                                                             |

        |------|-----------------------------------------------------------------------------------------------------------------------------------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                    |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the specified metadata object. |


        > ###### Note:

        > * This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > * This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation.
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseMessage'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseMessage'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/instructions/set:
    put:
      operationId: setAgentInstructions
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.6.0.cl or later</span>


        Creates or updates the admin instructions for the AI agent (Spotter). Admin instructions are tenant- and org-scoped text that guide agent behavior across all conversations. If instructions already exist for the org, they are replaced (upsert semantics).


        Requires admin privileges. Only users with org admin access can set agent instructions.


        #### Usage guidelines


        The request must include:


        - `instructions`: the instructions text to apply to the agent (maximum 5000 characters)


        Instructions are validated against system guardrails before being saved. If the instructions contain content that conflicts with guardrails, the request is rejected with a `409` error and the existing instructions remain unchanged.


        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


        #### Error responses


        | Code | Description |

        |------|-------------|

        | 400  | Bad request — the request body is missing required fields or the `instructions` field exceeds the maximum allowed length of 5000 characters. |

        | 401  | Unauthorized — authentication token is missing, expired, or invalid. |

        | 403  | Forbidden — the authenticated user does not have org admin privileges required to set agent instructions. |

        | 409  | Conflict — the provided instructions conflict with system guardrails. Review and revise the instructions text before retrying. |

        | 500  | Internal server error. |


        > ###### Note:

        >

        > - This operation uses upsert semantics: it creates the instructions record if none exists, or replaces the existing one.

        > - Instructions take effect immediately for new conversations created after the update.

        > - Use `getAgentInstructions` to retrieve the current instructions before making changes.

        > - Available from version 26.6.0.cl and later.





        #### Endpoint URL

        '
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetAgentInstructionsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstructions'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInstructions'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/instructions/set:
    post:
      operationId: setNLInstructions
      description: "\n<span class=\"since-beta-tag\">Beta</span> <span class=\"since-beta-tag\">Version: 10.15.0.cl or later</span>\n\nThis API allows users to set natural language (NL) instructions for a specific data-model to improve AI-generated answers and query processing. These instructions help guide the AI system to better understand the data context and provide more accurate responses.\n\nRequires `CAN_USE_SPOTTER` privilege, either edit access or `SPOTTER_COACHING_PRIVILEGE` on the data model, and a bearer token corresponding to the org where the data model exists.\n\n#### Usage guidelines\n\nTo set NL instructions for a data-model, the request must include:\n\n- `data_source_identifier`: The unique ID of the data-model for which to set NL instructions\n- `nl_instructions_info`: An array of instruction objects, each containing:\n  - `instructions`: Array of text instructions for the LLM\n  - `scope`: The scope of the instruction (`GLOBAL`). Currently only `GLOBAL` is supported. It can be extended to data-model-user scope in future.\n\n#### Instructions scope\n\n- **GLOBAL**: instructions that apply to all users querying this data model\n\nIf the request is successful, the API returns:\n\n- `success`: a boolean indicating whether the operation completed successfully\n\n#### Error responses\n\n| Code | Description                                                                                                                                                                                                                        |\n|------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                                                                                                               |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege, lacks edit access or `SPOTTER_COACHING_PRIVILEGE` on the data model, or the bearer token does not correspond to the org where the data model exists. |\n\n> ###### Note:\n>\n> - To use this API, the user needs either edit access or `SPOTTER_COACHING_PRIVILEGE` on the data model, and must use the bearer token corresponding to the org where the data model exists.\n> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.\n> - Available from version 10.15.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n> - Instructions help improve the accuracy and relevance of AI-generated responses for the specified data-model.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetNLInstructionsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_SetNLInstructionsResponse'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eureka_SetNLInstructionsResponse'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share:
    post:
      operationId: shareConversation
      description: "\nGrants or revokes access to a shared conversation for one or more principals\n(users or groups). When principals are added, a read-only shared view of the\nconversation is created from its current state. Use `refresh_shared_content`\nto regenerate the shared view with the latest conversation content.\nRequires `CAN_USE_SPOTTER` privilege and ownership of the specified conversation. <br/>  <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nGrants or revokes access to a shared conversation for one or more principals (users or groups). When principals are added, a read-only shared view of the conversation is created from its current state. The shared view is a point-in-time copy — use `refresh_shared_content` to regenerate it with the latest conversation content.\n\nRequires ownership of the specified conversation. Only the user who created the conversation can manage its share access.\n\n#### Usage guidelines\n\nThe conversation to share is identified by the `{conversation_identifier}` URL path parameter. At least one of the following must be true: `grant` is non-empty, `revoke` is non-empty, or `refresh_shared_content` is `true`. A principal cannot appear in both lists in the same request.\n\n| Field | Type | Default | Description |\n| --- | --- | --- | --- |\n| `refresh_shared_content` | `Boolean` | `false` | When `true`, always regenerates the shared view from the latest conversation state, even if a shared view already exists. When `false`, reuses the existing shared view. |\n| `grant` | `PrincipalRefInput[]` | `[]` | Principals to grant read-only access. |\n| `revoke` | `PrincipalRefInput[]` | `[]` | Principals to revoke access from. |\n| `notify_on_share` | `Boolean` | `true` | *(available from 26.10.0.cl)* When `true`, newly granted principals are notified of the share. When `false`, access is granted without sending a notification. Has no effect on principals passed in `revoke`, and does not re-notify a principal who already had access. |\n\n#### PrincipalRefInput fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `principal_identifier` | `String` | Unique identifier of the user or group. |\n| `principal_type` | `Principals` | `USER` for individual users, `USER_GROUP` for groups. |\n\n#### Example request — granting access\n\n```bash\nPOST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share\n```\n\n```json\n{\n  \"refresh_shared_content\": false,\n  \"grant\": [\n    { \"principal_identifier\": \"user-001\", \"principal_type\": \"USER\" },\n    { \"principal_identifier\": \"group-001\", \"principal_type\": \"USER_GROUP\" }\n  ],\n  \"revoke\": [],\n  \"notify_on_share\": true\n}\n```\n\n#### Example request — revoking access\n\n```json\n{\n  \"refresh_shared_content\": false,\n  \"grant\": [],\n  \"revoke\": [\n    { \"principal_identifier\": \"user-001\", \"principal_type\": \"USER\" }\n  ]\n}\n```\n\nSet `refresh_shared_content: true` with empty `grant` and `revoke` to regenerate the shared snapshot for existing recipients without changing access. Combine with non-empty `grant` or `revoke` to update access and refresh the snapshot in a single call.\n\n#### Error responses\n\n| Code | Description |\n| --- | --- |\n| 401 | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403 | Forbidden — the caller does not own the specified conversation, or does not have `CAN_USE_SPOTTER` privilege. |\n| 404 | Not Found — no conversation exists with the given identifier for the authenticated user. |\n| 422 | Unprocessable — `refresh_shared_content` is `false` and both `grant` and `revoke` are empty, or a principal appears in both lists. |\n\n> ###### Note:\n>\n> - The shared view is a read-only snapshot of the conversation at the time of sharing. Recipients cannot send messages or modify the conversation.\n> - Use `getShareInfo` to check whether the shared view is outdated relative to the current conversation state.\n> - `notify_on_share: false` only suppresses the share notification; access is still granted.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n<span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareConversationRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation to share.
      responses:
        '204':
          description: Successfully updated the share access for the conversation.
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/answer/create:
    post:
      operationId: singleAnswer
      description: '

        <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>


        Processes a natural language query against a specified data model and returns a single AI-generated answer without requiring a conversation session.


        Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.


        #### Usage guidelines


        The request must include:

        - `query`: a natural language question (e.g., "What were total sales last quarter?")

        - `metadata_identifier`: the unique ID of the data source to query against


        If the request is successful, the API returns a response message containing:

        - `session_identifier`: the unique ID of the generated response

        - `generation_number`: the generation number of the response

        - `message_type`: the type of the response (e.g., `TSAnswer`)

        - `visualization_type`: the generated visualization type (`Chart`, `Table`, or `Undefined`)

        - `tokens` / `display_tokens`: the search tokens and user-friendly display tokens for the response


        #### Error responses


        | Code | Description                                                                                                                             |

        |------|-----------------------------------------------------------------------------------------------------------------------------------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid.                                                                    |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the specified metadata object. |


        > ###### Note:

        > * This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.

        > * This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.





        #### Endpoint URL

        '
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleAnswerRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Common successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '201':
          description: Common error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response:
    post:
      operationId: stopConversation
      description: '

        Stops an in-progress agent conversation response. <br/>  <span class="since-beta-tag">Version: 26.6.0.cl or later</span>


        <span>Version: 26.6.0.cl or later</span>


        Stops an in-progress agent response for the specified conversation. Use this endpoint to cancel a response that is actively being generated — for example, when the user navigates away, reformulates their question, or no longer needs the current result.


        Requires `CAN_USE_SPOTTER` privilege and access to the specified conversation.


        #### Usage guidelines


        The request must include:


        - `conversation_identifier` *(path parameter)*: the unique ID of the conversation whose active response should be stopped, as returned by `createAgentConversation`


        A successful request returns an empty `204 No Content` response. If there is no active response in progress at the time of the call, the request is still treated as successful.


        After stopping a response, the conversation session remains active. You can continue sending messages using `sendAgentConversationMessage` or `sendAgentConversationMessageStreaming`.


        #### Example request


        ```bash

        POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response

        ```


        #### Typical usage scenario


        This endpoint is useful when integrating Spotter into a chat UI where users can cancel a long-running query. For example:


        1. User sends a message via `sendAgentConversationMessageStreaming`.

        2. User clicks a "Stop generating" button while the response is streaming.

        3. Your client calls `stopConversation` with the active `conversation_identifier`.

        4. The stream is terminated and the user can ask a new question.


        #### Error responses


        | Code | Description |

        |------|-------------|

        | 401  | Unauthorized — authentication token is missing, expired, or invalid. |

        | 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks access to the specified conversation. |


        > ###### Note:

        >

        > - Calling this endpoint when no response is in progress does not return an error.

        > - The conversation context is preserved after stopping — previous messages and answers remain accessible.

        > - Available from version 26.6.0.cl and later.

        > - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.

        > - This feature is available only for **Spotter 3** (`SPOTTER3`) version.





        #### Endpoint URL

        '
      tags:
      - AI
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation to stop.
      responses:
        '204':
          description: Successfully stopped the in-progress agent conversation response for the given.
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update:
    post:
      operationId: updateConversation
      description: "\nUpdates attributes of an existing agent conversation. Currently only the\ndisplay title can be updated; additional conversation attributes may be\nsupported in future versions. At least one updatable attribute must be\nprovided in the request body. <br/>  <span class=\"since-beta-tag\">Version: 26.7.0.cl or later</span>\n\nUpdates attributes of an existing saved agent conversation. Currently only the conversation's display `title` can be updated; additional updatable attributes may be supported in future versions. At least one updatable attribute must be supplied in the request body.\n\nRequires `CAN_USE_SPOTTER` privilege and ownership of the conversation being updated.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier` *(path parameter)*: the unique ID of the conversation to update, as returned by `createAgentConversation` or `getConversationList`\n- At least one updatable attribute in the request body:\n    - `title` *(optional)*: the new display name for the conversation. When provided, must be a non-empty string.\n\nA successful request returns an empty `204 No Content` response. Updated attributes are reflected immediately in subsequent calls to `getConversationList`.\n\n#### Example request\n\n```bash\nPOST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update\nContent-Type: application/json\n\n{\n  \"title\": \"Revenue Breakdown by Product Line\"\n}\n```\n\n#### Error responses\n\n| Code | Description |\n|------|-------------|\n| 400  | Bad Request — the request body is empty or `title` is provided as an empty string. |\n| 401  | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403  | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or does not own the specified conversation. |\n| 404  | Not Found — no conversation exists with the given `conversation_identifier` for the authenticated user. |\n| 422  | Unprocessable Entity — the request body is malformed or contains an invalid field value. |\n\n> ###### Note:\n>\n> - Only conversations created with `enable_save_chat: true` can be updated. Unsaved conversations are not persisted and do not have a retrievable identifier.\n> - Available from version 26.7.0.cl and later.\n> - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - AI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationRequest'
        required: true
      parameters:
      - in: path
        name: conversation_identifier
        required: true
        schema:
          type: string
        description: Unique identifier of the conversation to update.
      responses:
        '204':
          description: Successfully updated the agent conversation.
        '400':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Input_eureka_NLSRequest:
      type: object
      properties:
        agentVersion:
          type: integer
          format: int32
          description: Cluster version like 10.4.0.cl, 10.5.0.cl, so on.
          nullable: true
        bypassCache:
          type: boolean
          description: If true, results are not returned from cache & calculated every time. Can incur high costs & latency.
          nullable: true
        instructions:
          type: array
          items:
            type: string
          description: User specific instructions for processing the @query.
          nullable: true
        query:
          type: string
          description: User query which is a topical/goal oriented question that needs to be broken down into smaller simple analytical questions.
          nullable: true
    GetRelevantQuestionsRequest:
      type: object
      properties:
        metadata_context:
          description: metadata for the query to enable generation of relevant sub-questions; at least one context identifier is required.
          allOf:
          - $ref: '#/components/schemas/MetadataContext'
        limit_relevant_questions:
          description: Maximum number of relevant questions that is allowed in the response, default = 5.
          type: integer
          format: int32
        bypass_cache:
          description: If true, results are not returned from cache & calculated every time.
          type: boolean
          nullable: true
        query:
          description: A user query that requires breaking down into smaller, more manageable analytical questions to facilitate better understanding and analysis. Must be a non-empty string.
          type: string
        ai_context:
          description: Additional context to guide the response.
          allOf:
          - $ref: '#/components/schemas/AIContext'
      required:
      - metadata_context
      - query
    AgentConversation:
      type: object
      required:
      - conversation_id
      - conversation_identifier
      properties:
        conversation_id:
          type: string
          description: Unique identifier of the conversation.
        conversation_identifier:
          type: string
          description: 'Unique identifier of the conversation. <br/>  <span class="since-beta-tag">Version: 26.5.0.cl or later</span>'
    AgentConversationHistoryResponse:
      type: object
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationList'
          description: List of saved agent conversations for the current user.
          nullable: true
        has_more:
          type: boolean
          description: 'Whether additional conversations exist beyond this page. `true` when one or

            more conversations remain after the current page; `false` when the current

            page is the last. Use `offset` to fetch the next page.'
          nullable: true
      description: Response returned by getConversationList.
    ImportMemoryRequest:
      type: object
      properties:
        content:
          description: 'The full serialized memory payload to import (YAML) —

            typically a previous `exportMemory` response''s `content`, edited

            locally and re-submitted.'
          type: string
        dry_run:
          description: 'Required. When `true`, validate the payload and return preview

            counts and row failures without writing anything. Pass `false` to

            apply the import. The caller must choose explicitly so

            a real import is never triggered by omission.'
          type: boolean
      required:
      - content
      - dry_run
    eureka_LLMDecomposeQueryResponse:
      type: object
      properties:
        decomposedQueries:
          type: array
          items:
            $ref: '#/components/schemas/eureka_LLMSuggestedQuery'
          description: List of analytical questions that can be run on their respective worksheet/data sources.
          nullable: true
    NLInstructionsInfoInput:
      type: object
      required:
      - instructions
      - scope
      properties:
        instructions:
          type: array
          items:
            type: string
          description: User instructions for natural language processing.
        scope:
          type: string
          enum:
          - GLOBAL
          description: Scope of the instruction (USER or GLOBAL). Defaults to GLOBAL.
    eureka_RelevantQuestion:
      type: object
      properties:
        query:
          type: string
          description: NL query that can be run using spotter aka natural language search to get an AI generated answer.
          nullable: true
        data_source_identifier:
          type: string
          description: Unique identifier of the data source on which this query can be run on.
          nullable: true
        data_source_name:
          type: string
          description: Display name of the data source on which this query can be run on.
          nullable: true
    SingleAnswerRequest:
      type: object
      properties:
        query:
          description: A natural language query string to generate the Answer.
          type: string
        metadata_identifier:
          description: ID of the metadata object, such as a Worksheet or Model, to use as a data source for the query.
          type: string
      required:
      - query
      - metadata_identifier
    CreateAgentConversationRequest:
      type: object
      properties:
        metadata_context:
          description: Context for the conversation.
          allOf:
          - $ref: '#/components/schemas/ContextPayloadV2Input'
        conversation_settings:
          description: Conversation settings.
          allOf:
          - $ref: '#/components/schemas/ConversationSettingsInput'
      required:
      - metadata_context
      - conversation_settings
    ACState:
      type: object
      properties:
        transaction_identifier:
          type: string
          description: Unique identifier of the transaction.
          nullable: true
        generation_number:
          type: integer
          format: int32
          description: Generation number of the transaction.
          nullable: true
    SendAgentMessageStreamingRequest:
      type: object
      properties:
        conversation_identifier:
          description: Unique identifier for the conversation (used to track context)
          type: string
        messages:
          description: messages to be sent to the agent
          type: array
          items:
            type: string
      required:
      - conversation_identifier
      - messages
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          nullable: true
    ContextPayloadV2Input:
      type: object
      properties:
        type:
          type: string
          enum:
          - data_source
          - DATA_SOURCE
          - AUTO_MODE
          description: Type of the context.
          nullable: true
        data_source_context:
          $ref: '#/components/schemas/DataSourceContextInput'
          description: Data source context.
          nullable: true
    ImportMemoryResponse:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - SUCCESS
          - VALIDATION_FAILED
          - FAILED
          description: Terminal status of the import.
        summary:
          type: array
          items:
            $ref: '#/components/schemas/ImportSummary'
          description: 'Per (memory type, target source) result entries. Null when the

            import failed before any record processing occurred.'
          nullable: true
        validation_failures:
          type: array
          items:
            $ref: '#/components/schemas/ImportFailure'
          description: 'Per-item validation failure entries. Null when the import failed

            before item validation could run.'
          nullable: true
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/ImportDiagnostic'
          description: 'Diagnostic message groups (errors, rollbacks, and non-fatal

            warnings), each keyed by a `sub_status`. Null when the import

            produced no diagnostics.'
          nullable: true
        operation_id:
          type: string
          description: 'Server-generated identifier for this import operation. Include it in

            support tickets to help correlate server-side logs.'
          nullable: true
      description: 'Response from importMemory. On `SUCCESS`, `summary` is fully

        populated. `diagnostics` carries any fatal errors, rollbacks, and

        non-fatal warnings produced during the import.'
    ConversationSettingsInput:
      type: object
      properties:
        enable_contextual_change_analysis:
          type: boolean
          default: true
          description: 'Enable contextual change analysis.

            Default changed from `false` to `true` in 26.2.0.cl.

            Ignored on versions >= 26.2.0.cl where it is always enabled. <br/>  <span class="since-beta-tag">Version: 10.4.0.cl or later</span>'
          nullable: true
        enable_natural_language_answer_generation:
          type: boolean
          default: true
          description: 'Enable natural language to answer generation.

            Default changed from `false` to `true` in 26.2.0.cl.

            Ignored on versions >= 26.2.0.cl where it is always enabled. <br/>  <span class="since-beta-tag">Version: 10.4.0.cl or later</span>'
          nullable: true
        enable_reasoning:
          type: boolean
          default: true
          description: 'Enable reasoning.

            Default changed from `false` to `true` in 26.2.0.cl.

            Ignored on versions >= 26.2.0.cl where it is always enabled. <br/>  <span class="since-beta-tag">Version: 10.4.0.cl or later</span>'
          nullable: true
        enable_save_chat:
          type: boolean
          default: false
          description: 'Enable save conversation. When `true`, the conversation is persisted

            and can be retrieved later via conversation history. <br/>  <span class="since-beta-tag">Version: 26.5.0.cl or later</span>'
          nullable: true
    ShareConversationRequest:
      type: object
      properties:
        refresh_shared_content:
          description: 'When `true`, always regenerates the shared view from the latest conversation

            state, even if one already exists. When `false` (default), reuses the

            existing shared view.'
          default: false
          type: boolean
          nullable: true
        grant:
          description: Principals to grant read-only access to the conversation.
          default: []
          type: array
          items:
            $ref: '#/components/schemas/PrincipalRefInput'
        revoke:
          description: Principals to revoke access from the conversation.
          default: []
          type: array
          items:
            $ref: '#/components/schemas/PrincipalRefInput'
        notify_on_share:
          description: '<div><span class="since-beta-tag">Version: 26.10.0.cl or later</span></div>


            When `true` (default), newly granted principals are notified of the share. When `false`, access is granted without sending a notification. Has no effect on principals passed in `revoke`. Does not re-notify a principal who already had access.'
          default: true
          type: boolean
          nullable: true
      required:
      - grant
      - revoke
    SendMessageRequest:
      type: object
      properties:
        metadata_identifier:
          description: ID of the metadata object, such as a Worksheet or Model, to use as a data source for the conversation.
          type: string
        message:
          description: A message string with the follow-up question to continue the conversation.
          type: string
      required:
      - metadata_identifier
      - message
    ConversationShareStatusResponse:
      type: object
      required:
      - conversation_id
      - principals
      properties:
        conversation_id:
          type: string
          description: Unique identifier of the source conversation.
        is_shared_content_outdated:
          type: boolean
          description: '`true` when the shared view was generated before the last edit to the

            conversation and does not reflect the latest content. `null` when the

            conversation has never been shared.'
          nullable: true
        principals:
          type: array
          items:
            $ref: '#/components/schemas/ConversationPrincipalInfo'
          description: 'List of principals that currently have access to this shared conversation.

            Empty when no principals have been granted access.'
      description: Response returned by getShareInfo.
    ConversationMessage:
      type: object
      required:
      - message_id
      - timestamp_in_millis
      properties:
        message_id:
          type: string
          description: 'Stable identifier for the turn. For liveboard-started synthetic first turns,

            this is the root node identifier.'
        timestamp_in_millis:
          type: object
          description: Milliseconds since Unix epoch for the turn.
        user_prompt:
          $ref: '#/components/schemas/UserPrompt'
          description: 'User-authored prompt that started the turn: the user''s message and any files

            or connector resources attached to it. Null for liveboard-started synthetic

            first turns.'
          nullable: true
        response_items:
          type: array
          items:
            type: object
          description: 'Agent-side output produced in response to this turn. Empty array for

            in-progress turns where the agent has not yet produced output.'
          nullable: true
      description: 'One conversational exchange: an optional user prompt (message and attachments),

        followed by the agent''s response items for that turn.'
    SharedConversationResponse:
      type: object
      required:
      - conversation_id
      - shared_conversation_id
      - data_sources
      - messages
      - code_execution_files
      properties:
        conversation_id:
          type: string
          description: Unique identifier of the source conversation (echoes the request parameter).
        shared_conversation_id:
          type: string
          description: 'Identifier for the shared view. Use this as `conversation_identifier` in

            follow-up `loadAnswer` calls to hydrate answer items in the messages.'
        conversation_title:
          type: string
          description: Display title of the conversation.
          nullable: true
        data_sources:
          type: array
          items:
            $ref: '#/components/schemas/DataSourceEntry'
          description: Data sources used by the conversation, each with an identifier and display name.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
          description: 'Ordered conversation messages, oldest to newest. Same structure as the

            `messages` field returned by `getConversation`. Empty array when the

            conversation has no messages; never null.'
        code_execution_files:
          type: array
          items:
            $ref: '#/components/schemas/CodeExecutionFileMetadata'
          description: 'Sanitized metadata for files generated by the code-execution tool during

            this conversation. Empty when there are no such files.'
      description: 'Response returned by getSharedContent. Contains the full read-only view

        of the shared conversation including messages and data source metadata.'
    SendAgentConversationMessageStreamingRequest:
      type: object
      properties:
        messages:
          description: messages to be sent to the agent
          type: array
          items:
            type: string
      required:
      - messages
    eureka_DecomposeQueryResponse:
      type: object
      properties:
        decomposedQueryResponse:
          $ref: '#/components/schemas/eureka_LLMDecomposeQueryResponse'
          description: Decomposed query response for a topical/goal oriented question that contains broken down analytical questions.
          nullable: true
    UpdateConversationRequest:
      type: object
      properties:
        title:
          description: 'New display title for the conversation. Omit to leave the title

            unchanged.'
          type: string
    UserPrompt:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/UserMessage'
          description: User query that started the turn. Null for liveboard-started synthetic first turns.
          nullable: true
        attachments:
          type: array
          items:
            type: object
          description: 'Files or connector resources attached to the user message. Empty array when

            there are no attachments.'
          nullable: true
      description: 'User-authored prompt for a conversation turn: the user''s text message and any

        files or connector resources attached to it.'
    eureka_GetRelevantQuestionsResponse:
      type: object
      properties:
        relevant_questions:
          type: array
          items:
            $ref: '#/components/schemas/eureka_RelevantQuestion'
          description: List of relevant questions that can be run on their respective data sources.
          nullable: true
    MetadataContext:
      type: object
      properties:
        data_source_identifiers:
          type: array
          items:
            type: string
          description: List of data_source_identifiers to provide context for breaking down user query into analytical queries that can be run on them.
          nullable: true
        answer_identifiers:
          type: array
          items:
            type: string
          description: List of answer unique identifiers (GUIDs) whose data will be used to guide the response.
          nullable: true
        conversation_identifier:
          type: string
          description: Unique identifier to denote current conversation.
          nullable: true
        liveboard_identifiers:
          type: array
          items:
            type: string
          description: List of liveboard unique identifiers (GUIDs) whose data will be used to guide the response.
          nullable: true
    MemorySources:
      type: object
      required:
      - type
      - identifiers
      properties:
        type:
          type: string
          enum:
          - DATA_MODEL
          description: Source object type for this group. Must be `DATA_MODEL`.
        identifiers:
          type: array
          items:
            type: string
          description: 'Data-models to export memory for. Each entry may be a GUID or a

            human-readable obj_id; obj_ids are resolved server-side.'
      description: 'A single typed scope group identifying objects whose memory entries

        should be exported. One group binds a single `type` to a set of

        `identifiers`; pass one or more data-model identifiers in a group to

        scope the memory export to multiple data-models in one call.'
    DataSourceEntry:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier of the data source.
        name:
          type: string
          description: Display name of the data source.
      description: A data source associated with a conversation, returned as a typed entry.
    AnswerDetails:
      type: object
      properties:
        title:
          type: string
          description: Display title of the answer.
          nullable: true
        description:
          type: string
          description: Description of the answer.
          nullable: true
        session_identifier:
          type: string
          description: Unique identifier of the session.
          nullable: true
        generation_number:
          type: integer
          format: int32
          description: Generation number of the answer.
          nullable: true
        tokens:
          type: array
          items:
            type: string
          description: Ordered list of TML token strings that make up the answer query.
          nullable: true
        visualization_type:
          type: string
          enum:
          - Chart
          - CHART
          - Table
          - TABLE
          - Undefined
          - UNDEFINED
          description: Visualization type for the answer.
          nullable: true
        formulas:
          type: array
          items:
            type: string
          description: List of formulas used in the answer.
          nullable: true
        parameters:
          type: array
          items:
            type: string
          description: List of parameters used in the answer.
          nullable: true
        sub_queries:
          type: array
          items:
            type: object
          description: List of sub-queries used in the answer.
          nullable: true
        ac_state:
          $ref: '#/components/schemas/ACState'
          description: Agent context state for the answer.
          nullable: true
    ExportMemoryRequest:
      type: object
      properties:
        sources:
          description: 'List of typed scope groups selecting which data-models to export

            memory for. Supply `DATA_MODEL` group to scope the

            export to specific data-models.'
          type: array
          items:
            $ref: '#/components/schemas/MemorySources'
      required:
      - sources
    ConversationPrincipalInfo:
      type: object
      required:
      - id
      - type
      - display_name
      - name
      - permission
      properties:
        id:
          type: string
          description: Unique identifier of the user or group.
        type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Whether the principal is an individual user or a group.
        display_name:
          type: string
          description: Display name of the principal as shown in the UI.
        name:
          type: string
          description: Internal name of the principal.
        permission:
          type: string
          enum:
          - READ_ONLY
          - MODIFY
          - NO_ACCESS
          description: Access level granted to the principal. Always `READ_ONLY` for shared conversations.
      description: A principal that has been granted access to a shared conversation.
    ImportDiagnostic:
      type: object
      properties:
        sub_status:
          type: string
          enum:
          - UNKNOWN
          - FAILURE
          - WARNING
          - ROLLED_BACK
          description: 'Severity / disposition category these messages share (e.g.

            `WARNING`, `FAILURE`, `ROLLED_BACK`).'
          nullable: true
        messages:
          type: array
          items:
            type: string
          description: 'Human-readable messages for this category (e.g. the details of a

            `WARNING`, or the failure cause for a `FAILURE`).'
          nullable: true
      description: 'A group of importMemory diagnostic messages that share a severity /

        disposition. This is the single, uniform channel for fatal errors,

        rollbacks, and non-fatal observations.'
    SendAgentMessageRequest:
      type: object
      properties:
        messages:
          description: messages to be sent to the agent
          type: array
          items:
            type: string
      required:
      - messages
    Conversation:
      type: object
      required:
      - conversation_identifier
      properties:
        conversation_identifier:
          type: string
          description: Unique identifier of the conversation.
    GetDataSourceSuggestionsRequest:
      type: object
      properties:
        query:
          description: User query used to suggest data sources. Must be a non-empty string.
          type: string
      required:
      - query
    AIContext:
      type: object
      properties:
        instructions:
          type: array
          items:
            type: string
          description: User specific text instructions sent to AI system for processing the query.
          nullable: true
        content:
          type: array
          items:
            type: string
          description: User provided content like text data, csv data as a string message to provide context & potentially improve the quality of the response.
          nullable: true
    eureka_SetNLInstructionsResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Success status of the operation.
    ImportFailure:
      type: object
      properties:
        line_number:
          type: integer
          format: int32
          description: 'Best-effort line number of the offending item in the uploaded YAML. May be null when the line cannot be

            determined.'
          nullable: true
        reason:
          type: string
          enum:
          - UNKNOWN_FAILURE_REASON
          - VALIDATION
          - UNRESOLVED_SOURCE
          - ACCESS_DENIED
          - CHAR_LIMIT
          - SCHEMA
          description: 'Machine-readable category for the failure (e.g. `VALIDATION`,

            `ACCESS_DENIED`, `CHAR_LIMIT`).'
          nullable: true
        field_name:
          type: string
          description: 'Dotted path to the offending field within the item (e.g.

            `content.rule_definition`) for inline highlighting. Absent when the

            failure is item-level rather than field-level.'
          nullable: true
        message:
          type: string
          description: Human-readable description of the failure.
          nullable: true
      description: 'One per-item import failure surfaced by importMemory. `line_number` is

        the best-effort line number in the uploaded YAML; `field_name` is a

        dotted path within the item (e.g. `content.rule_definition`) for inline

        highlighting; absent when the failure is item-level rather than field-level.'
    CodeExecutionFileMetadata:
      type: object
      required:
      - file_id
      - expired
      properties:
        file_id:
          type: string
          description: 'Unique identifier of the code-execution-generated file. Stable across

            conversation turns.'
        display_name:
          type: string
          description: Human-readable file name.
          nullable: true
        file_type:
          type: string
          description: 'File type hint. Either a MIME string (e.g. `text/csv`) or an extension

            (e.g. `csv`).'
          nullable: true
        created_time_in_millis:
          type: object
          description: Milliseconds since Unix epoch when the file was created.
          nullable: true
        expired:
          type: boolean
          description: True when the file is no longer downloadable (storage expired or evicted).
      description: 'Sanitized public metadata for a code-execution-generated file. Internal

        storage identifiers (e.g. Azure blob ids) are deliberately not exposed.'
    eureka_DataSourceSuggestionResponse:
      type: object
      properties:
        data_sources:
          type: array
          items:
            $ref: '#/components/schemas/DataSource'
          description: List of data sources suggested.
          nullable: true
    SetNLInstructionsRequest:
      type: object
      properties:
        data_source_identifier:
          description: Unique ID or name of the data-model for which to set NL instructions.
          type: string
        nl_instructions_info:
          description: List of NL instructions to set for the data-model.
          type: array
          items:
            $ref: '#/components/schemas/NLInstructionsInfoInput'
      required:
      - data_source_identifier
      - nl_instructions_info
    CreateConversationRequest:
      type: object
      properties:
        metadata_identifier:
          description: ID of the metadata object, such as a Worksheet or Model, to use as a data source for the conversation.
          type: string
        tokens:
          description: Token string to set the context for the conversation. For example,`[sales],[item type],[state]`.
          type: string
      required:
      - metadata_identifier
    ConversationMessageResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
          description: Ordered conversation messages. Empty array when the conversation has no messages.
          nullable: true
        code_execution_files:
          type: array
          items:
            $ref: '#/components/schemas/CodeExecutionFileMetadata'
          description: 'Sanitized code-execution file metadata for files referenced by this

            conversation. Empty array when the conversation has no code-execution files.'
          nullable: true
      description: 'Response body of getConversation. `messages` is ordered oldest to newest.

        `code_execution_files` is a list of sanitized code-execution file metadata

        entries, keyed in upstream by `file_id`.'
    DataSource:
      type: object
      properties:
        confidence:
          type: number
          format: float
          description: Confidence score for the data source suggestion.
          nullable: true
        details:
          $ref: '#/components/schemas/EntityHeader'
          description: Details of the data source.
          nullable: true
        reasoning:
          type: string
          description: LLM reasoning for the data source.
          nullable: true
    NLInstructionsInfo:
      type: object
      required:
      - instructions
      - scope
      properties:
        instructions:
          type: array
          items:
            type: string
          description: User instructions for natural language processing.
        scope:
          type: string
          enum:
          - GLOBAL
          description: Scope of the instruction.
    eureka_LLMSuggestedQuery:
      type: object
      properties:
        query:
          type: string
          description: NL query that can be run using spotter aka natural language search to get an AI generated answer.
          nullable: true
        worksheetId:
          type: string
          description: Unique identifier of the worksheet on which this query can be run on.
          nullable: true
        worksheetName:
          type: string
          description: Display name of the worksheet on which this query can be run on.
          nullable: true
    eureka_GetNLInstructionsResponse:
      type: object
      required:
      - nl_instructions_info
      properties:
        nl_instructions_info:
          type: array
          items:
            $ref: '#/components/schemas/NLInstructionsInfo'
          description: List of NL instructions with their scopes.
    SendAgentMessageResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the agent response was received and processed successfully.
        message:
          type: string
          description: Optional message providing additional context about the operation outcome.
          nullable: true
    SetAgentInstructionsRequest:
      type: object
      properties:
        instructions:
          description: The admin instructions text to set for the agent.
          type: string
      required:
      - instructions
    ExportMemoryResponse:
      type: object
      properties:
        content:
          type: string
          description: 'Serialized memory payload (YAML). This is the shape

            importMemory consumes.'
          nullable: true
      description: 'Response from exportMemory. Contains the serialized payload

        ready for local editing and re-submission to importMemory.'
    PrincipalRefInput:
      type: object
      required:
      - principal_identifier
      - principal_type
      properties:
        principal_identifier:
          type: string
          description: Unique identifier of the user or group.
        principal_type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Whether the principal is an individual user or a group.
      description: 'Input reference to a principal (user or group) used when granting or revoking

        access to a shared resource.'
    GetNLInstructionsRequest:
      type: object
      properties:
        data_source_identifier:
          description: Unique ID or name of the data-model for which to retrieve NL instructions.
          type: string
      required:
      - data_source_identifier
    LoadAnswerResponse:
      type: object
      properties:
        answer:
          $ref: '#/components/schemas/AnswerDetails'
          description: Answer details for the loaded message.
          nullable: true
    ImportTargetSource:
      type: object
      properties:
        identifier:
          type: string
          description: Identifier (GUID) of the target object these counts apply to.
          nullable: true
        type:
          type: string
          enum:
          - DATA_MODEL
          description: Source object kind (`DATA_MODEL`).
          nullable: true
      description: 'Identifies the target object a group of import counts applies to.

        `type` is the source kind (`DATA_MODEL`) and `identifier` is

        the object''s GUID.'
    QueryGetDecomposedQueryRequest:
      type: object
      properties:
        answerIds:
          description: List of answer unique identifiers (GUIDs) whose data will be used to guide the response.
          type: array
          items:
            type: string
        content:
          description: User provided content like text data, csv data as a string message to provide context & potentially improve the quality of the response.
          type: array
          items:
            type: string
        conversationId:
          description: Unique identifier to denote current conversation.
          type: string
        liveboardIds:
          description: List of liveboard unique identifiers (GUIDs) whose data will be used to guide the response.
          type: array
          items:
            type: string
        maxDecomposedQueries:
          description: Maximum number of decomposed queries that is allowed in the response, default = 5.
          type: integer
          format: int32
        nlsRequest:
          description: NLSRequest object containing user query & instructions.
          allOf:
          - $ref: '#/components/schemas/Input_eureka_NLSRequest'
        worksheetIds:
          description: List of worksheetIds to provide context for decomposing user query into analytical queries that can be run on them.
          type: array
          items:
            type: string
    AgentConversationList:
      type: object
      required:
      - conversation_identifier
      properties:
        conversation_identifier:
          type: string
          description: Unique identifier of the conversation.
        conversation_title:
          type: string
          description: Display title of the conversation.
          nullable: true
        created_at:
          type: string
          description: ISO 8601 timestamp when the conversation was created.
          nullable: true
        updated_at:
          type: string
          description: ISO 8601 timestamp when the conversation was last updated.
          nullable: true
        data_source_identifiers:
          type: array
          items:
            type: string
          description: Unique identifiers of the data sources associated with the conversation.
          nullable: true
        data_source_names:
          type: array
          items:
            $ref: '#/components/schemas/DataSourceEntry'
          description: Data sources associated with the conversation, each with an `id` and `name`.
          nullable: true
      description: A saved agent conversation item returned in list responses.
    ResponseMessage:
      type: object
      required:
      - message_type
      properties:
        session_identifier:
          type: string
          description: Unique identifier of the generated response.
          nullable: true
        generation_number:
          type: integer
          format: int32
          description: Generate number of the response.
          nullable: true
        message_type:
          type: string
          enum:
          - TSAnswer
          description: Type of the generated response.
        visualization_type:
          type: string
          enum:
          - Chart
          - CHART
          - Table
          - TABLE
          - Undefined
          - UNDEFINED
          description: Generated visualization type.
          nullable: true
        tokens:
          type: string
          description: Tokens for the response.
          nullable: true
        display_tokens:
          type: string
          description: User friendly tokens for the response.
          nullable: true
    UserMessage:
      type: object
      required:
      - message_id
      - content
      properties:
        message_id:
          type: string
          description: Unique identifier of the user message.
        content:
          type: string
          description: Text body of the user query.
      description: 'User-authored text message that begins a conversation turn.

        Null when the turn is a synthetic liveboard-started first turn.'
    ImportSummary:
      type: object
      properties:
        memory_type:
          type: string
          enum:
          - RULES
          - RECIPES
          - ALWAYS_APPLY_RULES
          description: 'The kind of memory (`RULES`, `RECIPES`, or `ALWAYS_APPLY_RULES`)

            these counts apply to.'
          nullable: true
        source:
          $ref: '#/components/schemas/ImportTargetSource'
          description: The target object these counts apply to.
          nullable: true
        existing_record_count:
          type: integer
          format: int32
          description: 'Number of memory entries of this type that already existed on the

            target object before the import.'
          nullable: true
        deleted_record_count:
          type: integer
          format: int32
          description: 'Number of existing entries that will be (DRY_RUN) or were

            (EXECUTE_IMPORT) deleted as part of the replacement.'
          nullable: true
        inserted_record_count:
          type: integer
          format: int32
          description: 'Number of entries from the payload that will be (DRY_RUN) or were

            (EXECUTE_IMPORT) inserted.'
          nullable: true
        failed_record_count:
          type: integer
          format: int32
          description: Number of records of this type that failed validation or processing.
          nullable: true
      description: 'Per (memory type, target source) summary of what importMemory did — or

        would do, in DRY_RUN. `deleted_record_count` and `inserted_record_count`

        are previews in DRY_RUN and actuals in EXECUTE_IMPORT.'
    SendAgentConversationMessageRequest:
      type: object
      properties:
        messages:
          description: messages to be sent to the agent
          type: array
          items:
            type: string
      required:
      - messages
    EntityHeader:
      type: object
      properties:
        description:
          type: string
          description: Description of the data source.
          nullable: true
        data_source_name:
          type: string
          description: Display name of the data source.
          nullable: true
        data_source_identifier:
          type: string
          description: Unique identifier of the data source.
          nullable: true
    AgentInstructions:
      type: object
      required:
      - instructions
      properties:
        id:
          type: string
          description: Unique identifier of the record.
          nullable: true
        instructions:
          type: string
          description: The admin instructions text for the agent.
        created_at:
          type: string
          description: ISO timestamp when the instructions were created.
          nullable: true
        updated_at:
          type: string
          description: ISO timestamp when the instructions were last updated.
          nullable: true
        last_updated_by:
          type: string
          description: User ID of the admin who last updated the instructions.
          nullable: true
      description: Admin instructions configured for the AI agent.
    DataSourceContextInput:
      type: object
      properties:
        data_source_identifier:
          type: string
          description: 'Unique identifier of the data source.

            Required when context type is DATA_SOURCE and `data_source_identifiers` is not provided.

            At least one of `data_source_identifier` or `data_source_identifiers` must be supplied for DATA_SOURCE context;

            omit only when context type is AUTO_MODE. <br/>  <span class="since-beta-tag">Version: 26.5.0.cl or later</span>'
          nullable: true
        data_source_identifiers:
          type: array
          items:
            type: string
          description: 'Unique identifiers of data sources for multi-data-source context.

            Required when context type is DATA_SOURCE and `data_source_identifier` is not provided. <br/>  <span class="since-beta-tag">Version: 26.5.0.cl or later</span>'
          nullable: true
        guid:
          type: string
          description: 'Deprecated. Use `data_source_identifier` instead.

            Previously required when neither `data_source_identifier` nor `data_source_identifiers` was provided for DATA_SOURCE context. <br/>  <span class="since-beta-tag">Version: 26.2.0.cl or later</span>'
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-roles:
- name: 26.2.0.cl
  id: 26.2.0.cl
  tags:
  - 26.2.0.cl
  description: Roles for version 26.2.0.cl
- name: 10.4.0.cl
  id: 10.4.0.cl
  tags:
  - 10.4.0.cl
  description: Roles for version 10.4.0.cl
- name: 26.7.0.cl
  id: 26.7.0.cl
  tags:
  - 26.7.0.cl
  description: Roles for version 26.7.0.cl
- name: 26.8.0.cl
  id: 26.8.0.cl
  tags:
  - 26.8.0.cl
  description: Roles for version 26.8.0.cl
- name: 26.6.0.cl
  id: 26.6.0.cl
  tags:
  - 26.6.0.cl
  description: Roles for version 26.6.0.cl
- name: 10.15.0.cl
  id: 10.15.0.cl
  tags:
  - 10.15.0.cl
  description: Roles for version 10.15.0.cl
- name: 10.13.0.cl
  id: 10.13.0.cl
  tags:
  - 10.13.0.cl
  description: Roles for version 10.13.0.cl
- name: 26.9.0.cl
  id: 26.9.0.cl
  tags:
  - 26.9.0.cl
  description: Roles for version 26.9.0.cl
- name: 10.7.0.cl
  id: 10.7.0.cl
  tags:
  - 10.7.0.cl
  description: Roles for version 10.7.0.cl
- name: 26.5.0.cl
  id: 26.5.0.cl
  tags:
  - 26.5.0.cl
  description: Roles for version 26.5.0.cl
- name: 9.0.0.cl
  id: 9.0.0.cl
  tags:
  - 9.0.0.cl
  description: Roles for version 9.0.0.cl
- name: 9.4.0.cl
  id: 9.4.0.cl
  tags:
  - 9.4.0.cl
  description: Roles for version 9.4.0.cl
- name: 9.12.0.cl
  id: 9.12.0.cl
  tags:
  - 9.12.0.cl
  description: Roles for version 9.12.0.cl
- name: 26.4.0.cl
  id: 26.4.0.cl
  tags:
  - 26.4.0.cl
  description: Roles for version 26.4.0.cl
- name: 10.12.0.cl
  id: 10.12.0.cl
  tags:
  - 10.12.0.cl
  description: Roles for version 10.12.0.cl
- name: 9.2.0.cl
  id: 9.2.0.cl
  tags:
  - 9.2.0.cl
  description: Roles for version 9.2.0.cl
- name: 9.9.0.cl
  id: 9.9.0.cl
  tags:
  - 9.9.0.cl
  description: Roles for version 9.9.0.cl
- name: 9.6.0.cl
  id: 9.6.0.cl
  tags:
  - 9.6.0.cl
  description: Roles for version 9.6.0.cl
- name: 10.10.0.cl
  id: 10.10.0.cl
  tags:
  - 10.10.0.cl
  description: Roles for version 10.10.0.cl
- name: 10.6.0.cl
  id: 10.6.0.cl
  tags:
  - 10.6.0.cl
  description: Roles for version 10.6.0.cl
- name: 10.3.0.cl
  id: 10.3.0.cl
  tags:
  - 10.3.0.cl
  description: Roles for version 10.3.0.cl
- name: 10.1.0.cl
  id: 10.1.0.cl
  tags:
  - 10.1.0.cl
  description: Roles for version 10.1.0.cl
- name: 10.9.0.cl
  id: 10.9.0.cl
  tags:
  - 10.9.0.cl
  description: Roles for version 10.9.0.cl
- name: 10.8.0.cl
  id: 10.8.0.cl
  tags:
  - 10.8.0.cl
  description: Roles for version 10.8.0.cl
- name: 9.5.0.cl
  id: 9.5.0.cl
  tags:
  - 9.5.0.cl
  description: Roles for version 9.5.0.cl
- name: 26.3.0.cl
  id: 26.3.0.cl
  tags:
  - 26.3.0.cl
  description: Roles for version 26.3.0.cl
- name: 10.14.0.cl
  id: 10.14.0.cl
  tags:
  - 10.14.0.cl
  description: Roles for version 10.14.0.cl
- name: 9.7.0.cl
  id: 9.7.0.cl
  tags:
  - 9.7.0.cl
  description: Roles for version 9.7.0.cl