ThoughtSpot Semantic Integrations API

openapi: 3.2.0
info:
  title: ThoughtSpot Public REST Semantic Integrations API
  version: '2.0'
servers:
- url: '{base-url}'
  variables:
    base-url:
      default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: Semantic Integrations
paths:
  /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:
      - Semantic Integrations
      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:
      - Semantic Integrations
      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:
      - Semantic Integrations
      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:
      - Semantic Integrations
      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:
    SemanticIntegrationTagReference:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the tag.
        name:
          type:
          - string
          - 'null'
          description: Name of the tag.
      description: Tag reference associated with a semantic integration.
    SemanticIntegrationReportSummary:
      type: object
      properties:
        total:
          type:
          - integer
          - 'null'
          format: int32
          description: Total number of formulas.
        imported:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of successfully imported formulas.
        failed:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of failed formula imports.
        skipped:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of skipped formulas.
      description: Formula import counts summary.
    ErrorResponse:
      type: object
      properties:
        error:
          type:
          - object
          - 'null'
    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
    SemanticIntegrationResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the semantic integration.
        name:
          type:
          - string
          - 'null'
          description: Name of the semantic integration.
        model_id:
          type:
          - string
          - 'null'
          description: Model GUID generated for this integration.
        model_name:
          type:
          - string
          - 'null'
          description: Model name generated for this integration.
        semantic_report:
          $ref: '#/components/schemas/SemanticIntegrationReport'
          description: Per-formula import report.
      description: Response object for a semantic integration.
    SemanticIntegrationSortOptions:
      type: object
      properties:
        field_name:
          type:
          - string
          - 'null'
          enum:
          - NAME
          - AUTHOR
          - CREATED_TIME
          - MODIFIED_TIME
          description: Name of the field to apply the sort on.
        order:
          type:
          - string
          - 'null'
          enum:
          - ASC
          - DESC
          description: 'Sort order: `ASC` for ascending, `DESC` for descending.'
      description: Sort options for semantic integration search.
    SemanticIntegrationFormulaReport:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Formula ID in the model.
        name:
          type:
          - string
          - 'null'
          description: Formula name.
        description:
          type:
          - string
          - 'null'
          description: Formula description.
        source_expression:
          type:
          - string
          - 'null'
          description: CDW source expression.
        translated_formula:
          type:
          - string
          - 'null'
          description: ThoughtSpot formula equivalent.
        import_status:
          type:
          - string
          - 'null'
          enum:
          - IMPORTED
          - FAILED
          - SKIPPED
          description: Import status.
        change_status:
          type:
          - string
          - 'null'
          enum:
          - NEW
          - UPDATED
          - UNCHANGED
          description: Change status since last import. Null on initial create.
      description: Import details for a single formula.
    SemanticIntegrationReport:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/SemanticIntegrationReportSummary'
          description: Summary of formula import counts.
        formulas:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SemanticIntegrationFormulaReport'
          description: Formula import details.
      description: Per-formula import report for a semantic integration.
    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
    SemanticIntegrationSearchResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the semantic integration.
        name:
          type:
          - string
          - 'null'
          description: Name of the semantic integration.
        description:
          type:
          - string
          - 'null'
          description: Optional description of the semantic integration.
        model_id:
          type:
          - string
          - 'null'
          description: GUID of the associated ThoughtSpot model generated for this integration.
        model_name:
          type:
          - string
          - 'null'
          description: Name of the associated ThoughtSpot model.
        import_type:
          type:
          - string
          - 'null'
          enum:
          - CDW
          - FILE
          description: How the semantic definition was sourced.
        type:
          type:
          - string
          - 'null'
          enum:
          - RDBMS_SNOWFLAKE
          description: CDW connector type.
        connection_id:
          type:
          - string
          - 'null'
          description: GUID of the CDW connection backing the integration.
        connection_name:
          type:
          - string
          - 'null'
          description: Display name of the CDW connection backing the integration.
        author_id:
          type:
          - string
          - 'null'
          description: GUID of the user who created the integration.
        author_name:
          type:
          - string
          - 'null'
          description: Username of the user who created the integration.
        creation_time_in_millis:
          type:
          - number
          - 'null'
          format: float
          description: Creation time in Unix epoch milliseconds.
        modification_time_in_millis:
          type:
          - number
          - 'null'
          format: float
          description: Last modification time in Unix epoch milliseconds.
        tags:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SemanticIntegrationTagReference'
          description: Tags associated with the integration.
      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