ThoughtSpot
ThoughtSpot Variable API

The Variable API from ThoughtSpot — 7 operation(s) for variable.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: ThoughtSpot Public REST 10.1.0.cl Variable API
  version: '2.0'
servers:
- url: '{base-url}'
  variables:
    base-url:
      default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: Variable
paths:
  /api/rest/2.0/template/variables/create:
    post:
      operationId: createVariable
      description: '

        Create a variable which can be used for parameterizing metadata objects <br/>  <span class="since-beta-tag">Version: 26.4.0.cl or later</span>


        Allows creating a variable which can be used for parameterizing metadata objects in ThoughtSpot.


        Requires ADMINISTRATION role and TENANT scope.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint supports the following types of variables:

        * CONNECTION_PROPERTY - For connection properties

        * TABLE_MAPPING - For table mappings

        * CONNECTION_PROPERTY_PER_PRINCIPAL - For connection properties per principal. In order to use this please contact support to enable this.

        * FORMULA_VARIABLE - For Formula variables, introduced in 10.15.0.cl


        When creating a variable, you need to specify:

        * The variable type

        * A unique name for the variable

        * Whether the variable contains sensitive values (defaults to false)

        * The data type of the variable, only specify for formula variables (defaults to null)


        The operation will fail if:

        * The user lacks required permissions

        * The variable name already exists

        * The variable type is invalid




        #### Endpoint URL

        '
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVariableRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: Create variable is successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variable'
        '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/template/variables/{identifier}/delete:
    post:
      operationId: deleteVariable
      description: "\nDelete a variable <br/>  <span class=\"since-beta-tag\">Version: 10.14.0.cl or later</span>\n\n**Note:** This API endpoint is deprecated and will be removed from ThoughtSpot in a future release. Use [POST /api/rest/2.0/template/variables/delete](/api/rest/2.0/template/variables/delete) instead.\n\nAllows deleting a variable from ThoughtSpot.\n\nRequires ADMINISTRATION role and TENANT scope.\nThe CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.\n\nThe API endpoint requires:\n* The variable identifier (ID or name)\n\nThe operation will fail if:\n* The user lacks required permissions\n* The variable doesn't exist\n* The variable is being used by other objects \n\n\n\n#### Endpoint URL\n"
      deprecated: true
      tags:
      - Variable
      parameters:
      - in: path
        name: identifier
        required: true
        schema:
          type: string
        description: Unique id or name of the variable
      responses:
        '204':
          description: Deleting the variable is successful.
        '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/template/variables/delete:
    post:
      operationId: deleteVariables
      description: '

        Delete variable(s) <br/>  <span class="since-beta-tag">Version: 26.4.0.cl or later</span>


        Allows deleting multiple variables from ThoughtSpot.


        Requires ADMINISTRATION role and TENANT scope.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint requires:

        * The variable identifiers (IDs or names)


        The operation will fail if:

        * The user lacks required permissions

        * Any of the variables don''t exist

        * Any of the variables are being used by other objects





        #### Endpoint URL

        '
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteVariablesRequest'
        required: true
      parameters: []
      responses:
        '204':
          description: Deletion of variable(s) is successful.
        '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/template/variables/{identifier}/update-values:
    post:
      operationId: putVariableValues
      description: '

        Update values for a variable <br/>  <span class="since-beta-tag">Version: 26.4.0.cl or later</span>


        Allows updating values for a specific variable in ThoughtSpot.


        Requires ADMINISTRATION role.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint allows:

        * Adding new values to the variable

        * Replacing existing values

        * Deleting values from the variable

        * Resetting all values


        When updating variable values, you need to specify:

        * The variable identifier (ID or name)

        * The values to add/replace/remove

        * The operation to perform (ADD, REPLACE, REMOVE, RESET)


        Behaviour based on operation type:

        * ADD - Adds values to the variable if this is a list type variable, else same as replace.

        * REPLACE - Replaces all values of a given set of constraints with the current set of values.

        * REMOVE - Removes any values which match the set of conditions of the variables if this is a list type variable, else clears value.

        * RESET - Removes all constraints for the given variable, scope is ignored





        #### Endpoint URL

        '
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutVariableValuesRequest'
        required: true
      parameters:
      - in: path
        name: identifier
        required: true
        schema:
          type: string
        description: Unique ID or name of the variable
      responses:
        '204':
          description: Variable values updated 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/template/variables/search:
    post:
      operationId: searchVariables
      description: '

        Search variables <br/>  <span class="since-beta-tag">Version: 26.4.0.cl or later</span>


        Allows searching for variables in ThoughtSpot.


        Requires ADMINISTRATION role.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint supports searching variables by:

        * Variable identifier (ID or name)

        * Variable type

        * Name pattern (case-insensitive, supports % for wildcard)


        The search results can be formatted in three ways:

        * METADATA - Returns only variable metadata (default)

        * METADATA_AND_VALUES - Returns variable metadata and values


        The values can be filtered by scope:

        * org_identifier

        * principal_identifier

        * model_identifier





        #### Endpoint URL

        '
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchVariablesRequest'
        required: true
      parameters: []
      responses:
        '200':
          description: List of variables is successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Variable'
        '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/template/variables/{identifier}/update:
    post:
      operationId: updateVariable
      description: '

        Update a variable''s name <br/>  <span class="since-beta-tag">Version: 26.4.0.cl or later</span>


        Allows updating a variable''s name in ThoughtSpot.


        Requires ADMINISTRATION role and TENANT scope.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint allows updating:

        * The variable name




        #### Endpoint URL

        '
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVariableRequest'
        required: true
      parameters:
      - in: path
        name: identifier
        required: true
        schema:
          type: string
        description: Unique id or name of the variable to update.
      responses:
        '204':
          description: Variable name updated 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/template/variables/update-values:
    post:
      operationId: updateVariableValues
      description: '

        Update values for multiple variables <br/>  <span class="since-beta-tag">Version: 10.14.0.cl or later</span>


        **Note:** This API endpoint is deprecated and will be removed from ThoughtSpot in a future release. Use [POST /api/rest/2.0/template/variables/{identifier}/update-values](/api/rest/2.0/template/variables/%7Bidentifier%7D/update-values) instead.


        Allows updating values for multiple variables in ThoughtSpot.


        Requires ADMINISTRATION role.

        The CAN_MANAGE_VARIABLES permission allows you to manage Formula Variables in the current organization scope.


        The API endpoint allows:

        * Adding new values to variables

        * Replacing existing values

        * Deleting values from variables


        When updating variable values, you need to specify:

        * The variable identifiers

        * The values to add/replace/remove for each variable

        * The operation to perform (ADD, REPLACE, REMOVE, RESET)


        Behaviour based on operation type:

        * ADD - Adds values to the variable if this is a list type variable, else same as replace.

        * REPLACE - Replaces all values of a given set of constraints with the current set of values.

        * REMOVE - Removes any values which match the set of conditions of the variables if this is a list type variable, else clears value.

        * RESET - Removes all constrains for a given variable, scope is ignored





        #### Endpoint URL

        '
      deprecated: true
      tags:
      - Variable
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVariableValuesRequest'
        required: true
      parameters: []
      responses:
        '204':
          description: Variable values updated 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'
components:
  schemas:
    VariableUpdateScopeInput:
      type: object
      required:
      - org_identifier
      properties:
        org_identifier:
          type: string
          description: The unique name of the org
        principal_type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Type of principal to which the variable value applies. Use USER to assign values to a specific user, or USER_GROUP to assign values to a group.
          nullable: true
        principal_identifier:
          type: string
          description: Unique ID or name of the principal
          nullable: true
        model_identifier:
          type: string
          description: Unique ID or name of the model. Required for FORMULA_VARIABLE type to scope the variable value to a specific worksheet.
          nullable: true
        priority:
          type: integer
          format: int32
          description: The priority level for this scope assignment, used for conflict resolution when multiple values match. Higher priority values (larger numbers) take precedence.
          nullable: true
      description: Input for defining the scope of variable value assignments in batch update operations
    PutVariableValuesRequest:
      type: object
      properties:
        operation:
          description: Operation to perform
          type: string
          enum:
          - ADD
          - REMOVE
          - REPLACE
          - RESET
        variable_assignment:
          description: Variable assignments
          type: array
          items:
            $ref: '#/components/schemas/VariablePutAssignmentInput'
      required:
      - variable_assignment
    UpdateVariableRequest:
      type: object
      properties:
        name:
          description: New name of the variable.
          type: string
      required:
      - name
    VariableDetailInput:
      type: object
      properties:
        identifier:
          type: string
          description: Unique ID or name of the variable
          nullable: true
        type:
          type: string
          enum:
          - CONNECTION_PROPERTY
          - TABLE_MAPPING
          - CONNECTION_PROPERTY_PER_PRINCIPAL
          - FORMULA_VARIABLE
          - USER_PROPERTY
          description: Type of variable
          nullable: true
        name_pattern:
          type: string
          description: A pattern to match case-insensitive name of the variable. User % for a wildcard match
          nullable: true
      description: Input for variable details in search
    Variable:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Unique identifier of the variable
        name:
          type: string
          description: Name of the variable
        variable_type:
          type: string
          enum:
          - CONNECTION_PROPERTY
          - TABLE_MAPPING
          - CONNECTION_PROPERTY_PER_PRINCIPAL
          - FORMULA_VARIABLE
          - USER_PROPERTY
          description: Type of the variable
          nullable: true
        sensitive:
          type: boolean
          description: If the variable is sensitive
          nullable: true
        values:
          type: array
          items:
            $ref: '#/components/schemas/VariableValue'
          description: Values of the variable
          nullable: true
        org:
          $ref: '#/components/schemas/VariableOrgInfo'
          description: Owner org of the variable.
          nullable: true
      description: Variable object
    VariableOrgInfo:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int32
          description: ID of the Org.
        name:
          type: string
          description: Name of the Org.
    UpdateVariableValuesRequest:
      type: object
      properties:
        variable_assignment:
          description: Array of variable assignment objects specifying the variable identifier, values to assign, and the operation type (ADD, REMOVE, REPLACE, or RESET) to perform on each variable.
          type: array
          items:
            $ref: '#/components/schemas/VariableUpdateAssignmentInput'
        variable_value_scope:
          description: Array of scope objects defining where the variable values apply, including organization context, optional principal constraints (user or group), model reference for formula variables, and priority for conflict resolution.
          type: array
          items:
            $ref: '#/components/schemas/VariableUpdateScopeInput'
      required:
      - variable_assignment
      - variable_value_scope
    CreateVariableRequest:
      type: object
      properties:
        type:
          description: Type of variable
          type: string
          enum:
          - CONNECTION_PROPERTY
          - TABLE_MAPPING
          - CONNECTION_PROPERTY_PER_PRINCIPAL
          - FORMULA_VARIABLE
        name:
          description: Name of the variable. This is unique across the cluster.
          type: string
        is_sensitive:
          description: If the variable contains sensitive values like passwords
          default: false
          type: boolean
          nullable: true
        data_type:
          description: 'Variable Data Type, only for formula_variable type, leave empty for others <br/>  <span class="since-beta-tag">Version: 10.15.0.cl or later</span>'
          type: string
          enum:
          - VARCHAR
          - INT32
          - INT64
          - DOUBLE
          - DATE
          - DATE_TIME
      required:
      - type
      - name
    VariableUpdateAssignmentInput:
      type: object
      required:
      - variable_identifier
      - variable_values
      - operation
      properties:
        variable_identifier:
          type: string
          description: ID or Name of the variable
        variable_values:
          type: array
          items:
            type: string
          description: Values of the variable
        operation:
          type: string
          enum:
          - ADD
          - REMOVE
          - REPLACE
          - RESET
          description: Operation to perform
      description: Input for variable value update in batch operations
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          nullable: true
    SearchVariablesRequest:
      type: object
      properties:
        variable_details:
          description: Variable details
          type: array
          items:
            $ref: '#/components/schemas/VariableDetailInput'
        value_scope:
          description: Array of scope filters
          type: array
          items:
            $ref: '#/components/schemas/ValueScopeInput'
        record_offset:
          description: The starting record number from where the records should be included
          default: 0
          type: integer
          format: int32
        record_size:
          description: The number of records that should be included
          default: 10
          type: integer
          format: int32
        response_content:
          description: Format in which we want the output
          default: METADATA
          type: string
          enum:
          - METADATA
          - METADATA_AND_VALUES
    VariableValue:
      type: object
      required:
      - org_identifier
      properties:
        value:
          type: string
          description: The value of the variable
          nullable: true
        value_list:
          type: array
          items:
            type: string
          description: The value of the variable if it is a list type
          nullable: true
        org_identifier:
          type: string
          description: The unique name of the org
        principal_type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Type of principal to which this value applies. Use USER to assign the value to a specific user, or USER_GROUP to assign it to a group.
          nullable: true
        principal_identifier:
          type: string
          description: Unique ID or name of the principal
          nullable: true
        model_identifier:
          type: string
          description: 'Unique ID of the model <br/> <span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.3.0.cl or later</span>'
          nullable: true
        priority:
          type: integer
          format: int32
          description: The priority assigned to this value. If there are 2 matching values, the one with the higher priority will be picked.
          nullable: true
    DeleteVariablesRequest:
      type: object
      properties:
        identifiers:
          description: Unique id(s) or name(s) of the variable(s) to delete
          type: array
          items:
            type: string
      required:
      - identifiers
    ValueScopeInput:
      type: object
      properties:
        org_identifier:
          type: string
          description: The unique name of the org
          nullable: true
        principal_type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Type of principal to filter by. Use USER to filter values assigned to specific users, or USER_GROUP to filter values assigned to groups.
          nullable: true
        principal_identifier:
          type: string
          description: Unique ID or name of the principal
          nullable: true
        model_identifier:
          type: string
          description: Unique ID or name of the model to filter by. Applicable only for FORMULA_VARIABLE type.
          nullable: true
      description: Input for filtering variable values by scope in search operations
    VariablePutAssignmentInput:
      type: object
      required:
      - assigned_values
      properties:
        assigned_values:
          type: array
          items:
            type: string
          description: Values of the variable
        org_identifier:
          type: string
          description: The unique name of the org
          nullable: true
        principal_type:
          type: string
          enum:
          - USER
          - USER_GROUP
          description: Principal type
          nullable: true
        principal_identifier:
          type: string
          description: Unique ID or name of the principal
          nullable: true
        model_identifier:
          type: string
          description: Unique ID of the model
          nullable: true
        priority:
          type: integer
          format: int32
          description: Priority level
          nullable: true
      description: Input for variable value put operations
  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
ThoughtSpot Variable API

Documentation

Specifications

Other Resources

OpenAPI Specification
