openapi: 3.0.0
info:
  title: ThoughtSpot Public REST 10.1.0.cl 10.15.0.cl API
  version: '2.0'
servers:
- url: '{base-url}'
  variables:
    base-url:
      default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: 10.15.0.cl
paths:
  /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:
      - 10.15.0.cl
      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:
      - 10.15.0.cl
      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/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:
      - 10.15.0.cl
      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'
components:
  schemas:
    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
    GetDataSourceSuggestionsRequest:
      type: object
      properties:
        query:
          description: User query used to suggest data sources. Must be a non-empty string.
          type: string
      required:
      - query
    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.
    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
    eureka_SetNLInstructionsResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Success status of the operation.
    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
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          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.
    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
    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.
  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