openapi: 3.0.0
info:
  title: ThoughtSpot Public REST 10.1.0.cl 26.9.0.cl API
  version: '2.0'
servers:
- url: '{base-url}'
  variables:
    base-url:
      default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: 26.9.0.cl
paths:
  /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:
      - 26.9.0.cl
      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:
      - 26.9.0.cl
      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/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:
      - 26.9.0.cl
      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/semantic-integrations/create:
    post:
      operationId: createSemanticIntegration
      description: "\n <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nCreates a new semantic integration in ThoughtSpot from a CDW semantic view.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege or `DATAMANAGEMENT` (**Can manage data**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the following Data control privileges may be required:\n\n- `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**)\n- **Can manage data models**\n\n#### About create semantic integration\n\nA semantic integration imports an externally defined semantic view from a Cloud Data Warehouse (CDW) into ThoughtSpot. The API resolves the source semantic view from the specified `connection_identifier`, `database_name`, `schema_name`, and `semantic_view_name`, generates a ThoughtSpot model from it, and returns the model GUID along with a per-formula import report (`semantic_report`) summarizing how many formulas were successfully imported, failed, or skipped.\n\n- `connection_identifier`, `name`, `database_name`, `schema_name`, `semantic_view_name`, and `type` are required.\n- `name` must be unique across the user's organization. The integration's display name is also used as the generated model name.\n- Supported `type` values are listed in the `SemanticIntegrationType` enum (currently `RDBMS_SNOWFLAKE`).\n- The response includes a `semantic_report.summary` with `total`, `imported`, `failed`, and `skipped` counts, and a `formulas` array with the per-formula translation details.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - 26.9.0.cl
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSemanticIntegrationRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Semantic integration created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticIntegrationResponse'
        '400':
          description: Invalid request.
          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'
        '404':
          description: Connection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Duplicate integration name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete:
    post:
      operationId: deleteSemanticIntegration
      description: "\n <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nDeletes a semantic integration and its associated ThoughtSpot model.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege or `DATAMANAGEMENT` (**Can manage data**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the following Data control privileges may be required:\n\n- `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**)\n- **Can manage data models**\n\n#### About delete semantic integration\n\nRemoves the specified semantic integration and its generated ThoughtSpot model from the system.\n\n- `semantic_integration_identifier` is the GUID or name of the integration to delete.\n- Deletions cannot be undone. Re-import the integration with `createSemanticIntegration` if needed.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - 26.9.0.cl
      parameters:
      - in: path
        name: semantic_integration_identifier
        required: true
        schema:
          type: string
        description: ID or name of the semantic integration to delete.
      responses:
        '204':
          description: Semantic integration deleted successfully.
        '400':
          description: Invalid request.
          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: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import:
    post:
      operationId: importSemanticIntegration
      description: "\n <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nImports semantic updates for an existing semantic integration from its CDW source and refreshes the associated ThoughtSpot model.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege or `DATAMANAGEMENT` (**Can manage data**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the following Data control privileges may be required:\n\n- `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**)\n- **Can manage data models**\n\n#### About import semantic integration\n\nRe-imports the semantic view from the CDW for the specified integration and rebuilds the corresponding ThoughtSpot model. Use this after the source semantic view has been updated in the CDW (added, removed, or modified formulas, dimensions, or measures) to bring the ThoughtSpot model back in line.\n\n- `semantic_integration_identifier` is the GUID or name of the integration to import updates for.\n- Import preserves the integration's GUID, name, and `model_id`; only the underlying formula set is refreshed.\n- The response includes the same `semantic_report` as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - 26.9.0.cl
      parameters:
      - in: path
        name: semantic_integration_identifier
        required: true
        schema:
          type: string
        description: ID or name of the semantic integration to import updates for.
      responses:
        '200':
          description: Semantic integration imported successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticIntegrationResponse'
        '400':
          description: Invalid request.
          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'
        '404':
          description: Semantic integration not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/rest/2.0/semantic-integrations/search:
    post:
      operationId: searchSemanticIntegrations
      description: "\n <span class=\"since-beta-tag\">Version: 26.9.0.cl or later</span>\n\nSearches and lists semantic integrations available to the authenticated user in the current organization, with optional filters, sort, and pagination.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege or `DATAMANAGEMENT` (**Can manage data**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the following Data control privileges may be required:\n\n- `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**)\n- **Can manage data models**\n\n#### About search semantic integrations\n\nReturns a paginated batch of semantic integrations, each with its identifier, name, description, source connection, generated model identifier, author, creation/modification timestamps, and associated tags. Use the filters to narrow results by author, connection, tag, or name pattern.\n\n- `pattern` matches the integration name as a case-insensitive substring.\n- `author_identifiers` and `connection_identifiers` accept either GUIDs or names.\n- `sort_options.field_name` defaults to `MODIFIED_TIME`; set `sort_options.order` to `ASC` or `DESC` to control sort direction.\n- `record_offset` and `record_size` control pagination. Use `record_size: 0` to return all matching records in a single response.\n\n\n\n\n#### Endpoint URL\n"
      tags:
      - 26.9.0.cl
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchSemanticIntegrationsRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Semantic integrations retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SemanticIntegrationSearchResponse'
        '400':
          description: Invalid request.
          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: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SearchSemanticIntegrationsRequest:
      type: object
      properties:
        sort_options:
          description: Sort options for the search results.
          allOf:
          - $ref: '#/components/schemas/SemanticIntegrationSortOptions'
        record_offset:
          description: Number of records to skip for pagination. Minimum value is 0.
          default: 0
          type: integer
          format: int32
        record_size:
          description: Maximum number of records to return. Use 0 to return all records (no pagination).
          default: 10
          type: integer
          format: int32
        pattern:
          description: Name filter substring to narrow search results.
          type: string
        author_identifiers:
          description: Filter by author IDs or names who created the integrations.
          type: array
          items:
            type: string
        connection_identifiers:
          description: Filter by connection IDs or names associated with the integrations.
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          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
    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.'
    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.'
    CreateSemanticIntegrationRequest:
      type: object
      properties:
        connection_identifier:
          description: ID or name of the CDW connection.
          type: string
        name:
          description: Name of the semantic integration. Must be unique.
          type: string
        database_name:
          description: Database name in the CDW.
          type: string
        schema_name:
          description: Schema name in the CDW.
          type: string
        semantic_view_name:
          description: Semantic view name in the CDW.
          type: string
        type:
          description: CDW connector type.
          type: string
          enum:
          - RDBMS_SNOWFLAKE
        description:
          description: Optional description of the semantic integration.
          type: string
      required:
      - connection_identifier
      - name
      - database_name
      - schema_name
      - semantic_view_name
      - type
    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.
    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.
    SemanticIntegrationSortOptions:
      type: object
      properties:
        field_name:
          type: string
          enum:
          - NAME
          - AUTHOR
          - CREATED_TIME
          - MODIFIED_TIME
          description: Name of the field to apply the sort on.
          nullable: true
        order:
          type: string
          enum:
          - ASC
          - DESC
          description: 'Sort order: `ASC` for ascending, `DESC` for descending.'
          nullable: true
      description: Sort options for semantic integration search.
    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.'
    SemanticIntegrationReport:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/SemanticIntegrationReportSummary'
          description: Summary of formula import counts.
          nullable: true
        formulas:
          type: array
          items:
            $ref: '#/components/schemas/SemanticIntegrationFormulaReport'
          description: Formula import details.
          nullable: true
      description: Per-formula import report for a semantic integration.
    SemanticIntegrationResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the semantic integration.
          nullable: true
        name:
          type: string
          description: Name of the semantic integration.
          nullable: true
        model_id:
          type: string
          description: Model GUID generated for this integration.
          nullable: true
        model_name:
          type: string
          description: Model name generated for this integration.
          nullable: true
        semantic_report:
          $ref: '#/components/schemas/SemanticIntegrationReport'
          description: Per-formula import report.
          nullable: true
      description: Response object for a semantic integration.
    SemanticIntegrationFormulaReport:
      type: object
      properties:
        id:
          type: string
          description: Formula ID in the model.
          nullable: true
        name:
          type: string
          description: Formula name.
          nullable: true
        description:
          type: string
          description: Formula description.
          nullable: true
        source_expression:
          type: string
          description: CDW source expression.
          nullable: true
        translated_formula:
          type: string
          description: ThoughtSpot formula equivalent.
          nullable: true
        import_status:
          type: string
          enum:
          - IMPORTED
          - FAILED
          - SKIPPED
          description: Import status.
          nullable: true
        change_status:
          type: string
          enum:
          - NEW
          - UPDATED
          - UNCHANGED
          description: Change status since last import. Null on initial create.
          nullable: true
      description: Import details for a single formula.
    SemanticIntegrationReportSummary:
      type: object
      properties:
        total:
          type: integer
          format: int32
          description: Total number of formulas.
          nullable: true
        imported:
          type: integer
          format: int32
          description: Number of successfully imported formulas.
          nullable: true
        failed:
          type: integer
          format: int32
          description: Number of failed formula imports.
          nullable: true
        skipped:
          type: integer
          format: int32
          description: Number of skipped formulas.
          nullable: true
      description: Formula import counts summary.
    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.'
    SemanticIntegrationTagReference:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the tag.
          nullable: true
        name:
          type: string
          description: Name of the tag.
          nullable: true
      description: Tag reference associated with a semantic integration.
    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.'
    SemanticIntegrationSearchResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the semantic integration.
          nullable: true
        name:
          type: string
          description: Name of the semantic integration.
          nullable: true
        description:
          type: string
          description: Optional description of the semantic integration.
          nullable: true
        model_id:
          type: string
          description: GUID of the associated ThoughtSpot model generated for this integration.
          nullable: true
        model_name:
          type: string
          description: Name of the associated ThoughtSpot model.
          nullable: true
        import_type:
          type: string
          enum:
          - CDW
          - FILE
          description: How the semantic definition was sourced.
          nullable: true
        type:
          type: string
          enum:
          - RDBMS_SNOWFLAKE
          description: CDW connector type.
          nullable: true
        connection_id:
          type: string
          description: GUID of the CDW connection backing the integration.
          nullable: true
        connection_name:
          type: string
          description: Display name of the CDW connection backing the integration.
          nullable: true
        author_id:
          type: string
          description: GUID of the user who created the integration.
          nullable: true
        author_name:
          type: string
          description: Username of the user who created the integration.
          nullable: true
        creation_time_in_millis:
          type: number
          format: float
          description: Creation time in Unix epoch milliseconds.
          nullable: true
        modification_time_in_millis:
          type: number
          format: float
          description: Last modification time in Unix epoch milliseconds.
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/SemanticIntegrationTagReference'
          description: Tags associated with the integration.
          nullable: true
      description: Single semantic integration entry returned by search.
  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