TML API

Table of Contents

Supported operations
Import TML
Export TML
Export TML objects in bulk

The TML API endpoints allow you to programmatically export, validate, and import scriptable ThoughtSpot Modeling Language (TML) files. You can use these API endpoints to automate the change management and deployment processes between your development and production environments. With TML API, you can easily migrate your ThoughtSpot content from one environment to another by automating the entire change management process and thereby reducing the risk of human error.

Supported operations🔗

API endpoint Available from

API endpoint	Available from
`POST /tspublic/v1/metadata/tml/import` Imports object representations in the ThoughtSpot Modeling Language (TML) format.	ThoughtSpot Cloud ts7.may.cl ThoughtSpot Software 7.1.1
`POST /tspublic/v1/metadata/tml/export` Exports objects from ThoughtSpot as TML representations.	ThoughtSpot Cloud ts7.may.cl ThoughtSpot Software 7.1.1
`POST /tspublic/v1/metadata/tml/export/batch` Exports user, user group, and Role objects in TML format.	ThoughtSpot Cloud 10.1.0.cl ThoughtSpot Software 10.1.0.sw

POST /tspublic/v1/metadata/tml/import
Imports object representations in the ThoughtSpot Modeling Language (TML) format.

ThoughtSpot Cloud ts7.may.cl
ThoughtSpot Software 7.1.1

POST /tspublic/v1/metadata/tml/export
Exports objects from ThoughtSpot as TML representations.

ThoughtSpot Cloud ts7.may.cl
ThoughtSpot Software 7.1.1

POST /tspublic/v1/metadata/tml/export/batch
Exports user, user group, and Role objects in TML format.

ThoughtSpot Cloud 10.1.0.cl
ThoughtSpot Software 10.1.0.sw

Import TML🔗

To import TML representation of objects into ThoughtSpot, use the /tspublic/v1/metadata/tml/import API endpoint.

Resource URL🔗

POST /tspublic/v1/metadata/tml/import

Request parameters🔗

Form parameter Description Default

Form parameter	Description	Default
`import_objects`	String. An `x-www-form-urlencoded` string containing a JSON array of TML objects to upload, in YAML or JSON format. If in YAML format within the JSON array, use escape characters for YAML quotes, and new line characters when there is a new line. For example: To import a single object, `["guid: 3729c085-8659-48fd-9479-a67bd7307496\npinboard:\n name: …"]` To import multiple objects, `["guid: 3729c085-8659-48fd-9479-a67bd7307496\npinboard:\n name: …“, "guid: 5739d025-8659-48fd-9479-a67bd7704212\npinboard:\n name: …”]`	None
`import_policy`	String. Policy to follow during import. The allowed values are: `PARTIAL` Imports all objects that validate successfully, and ignores objects that do not validate successfully. `ALL_OR_NONE` Imports the objects that validate successfully. `VALIDATE_ONLY` Validates the objects but does not import them.	`PARTIAL`
`force_create`	Boolean. Specifies if you are updating or creating objects. To create new objects, specify `true`. By default, ThoughtSpot updates existing objects that have the same GUID as the objects you are importing. When set to `true`, the `guid` property in the imported TML is replaced with a new GUID if the GUID is being used by another object on the server. If the imported TML file includes a `guid` that is not used by any other object, ThoughtSpot creates a new object with the same `guid` from the imported TML file. To know GUID assigned to the new object created from TML import, check the `id_guid` property in the response headers.	`false`

import_objects

String. An x-www-form-urlencoded string containing a JSON array of TML objects to upload, in YAML or JSON format.

If in YAML format within the JSON array, use escape characters for YAML quotes, and new line characters when there is a new line.

For example:

To import a single object, ["guid: 3729c085-8659-48fd-9479-a67bd7307496\npinboard:\n name: …"]
To import multiple objects, ["guid: 3729c085-8659-48fd-9479-a67bd7307496\npinboard:\n name: …“, "guid: 5739d025-8659-48fd-9479-a67bd7704212\npinboard:\n name: …”]

None

import_policy

String. Policy to follow during import. The allowed values are:

PARTIAL
Imports all objects that validate successfully, and ignores objects that do not validate successfully.
ALL_OR_NONE
Imports the objects that validate successfully.
VALIDATE_ONLY
Validates the objects but does not import them.

PARTIAL

force_create

Boolean. Specifies if you are updating or creating objects. To create new objects, specify true.

By default, ThoughtSpot updates existing objects that have the same GUID as the objects you are importing. When set to true, the guid property in the imported TML is replaced with a new GUID if the GUID is being used by another object on the server.
If the imported TML file includes a guid that is not used by any other object, ThoughtSpot creates a new object with the same guid from the imported TML file.
To know GUID assigned to the new object created from TML import, check the id_guid property in the response headers.

false

Example request🔗

Make sure the API request has the following header:

Accept: text/plain

cURL

curl -X POST /
--header 'Accept: text/plain' /
--header 'X-Requested-By: ThoughtSpot' --data-urlencode 'import_objects=[{
	"guid": "12289fad-f230-485e-8c65-e36082eebf44",
	"answer": {
		"name": "Basic Answer 1",
		"description": "This is basic answer with table and headline visualizations.",
		"tables": [{
			"id": "LINEORDER",
			"name": "LINEORDER",
			"fqn": "2445fe81-30d6-46fa-9f42-f6b1b4e01623"
		}, {
			"id": "PART",
			"name": "PART",
			"fqn": "a7fc012e-bdb3-4e75-9ce4-b3f731d90136"
		}],
		"search_query": "[LINEORDER_1::Revenue] [PART_1::Color]",
		"answer_columns": [{
			"name": "Total Revenue"
		}, {
			"name": "Color"
		}],
		"table": {
			"table_columns": [{
				"column_id": "Color",
				"headline_aggregation": "COUNT_DISTINCT"
			}, {
				"column_id": "Total Revenue",
				"headline_aggregation": "SUM"
			}],
			"ordered_column_ids": ["Color", "Total Revenue"]
		},
		"chart": {
			"type": "COLUMN",
			"chart_columns": [{
				"column_id": "Total Revenue"
			}, {
				"column_id": "Color"
			}],
			"axis_configs": [{
				"x": ["Color"],
				"y": ["Total Revenue"]
			}]
		},
		"display_mode": "TABLE_MODE"
	}
}]'
--data-urlencode 'import_policy=PARTIAL'
--data-urlencode 'force_create=true'
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/import'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/import

Example response🔗

{
  "object": [
    {
      "response": {
        "status": {
          "status_code": "OK"
        },
        "header": {
          "id_guid": "a09a3787-e546-42cb-888f-c17260dd1229",
          "name": "Basic Answer 1",
          "description": "This is basic answer with table and headline visualizations.",
          "author_guid": "59481331-ee53-42be-a548-bd87be6ddd4a",
          "owner_guid": "a09a3787-e546-42cb-888f-c17260dd1229",
          "metadata_type": "QUESTION_ANSWER_BOOK"
        }
      }
    }
  ]
}

Response codes🔗

HTTP status code	Description
200	Successful import of the TML object representations
400	Bad request
401	Unauthorized or wrong credentials
403	Forbidden - incorrect permissions
404	Not found
500	Internal server error

HTTP status code

Description

200

Successful import of the TML object representations

400

Bad request

401

Unauthorized or wrong credentials

403

Forbidden - incorrect permissions

404

Not found

500

Internal server error

Export TML🔗

To export TML objects, use the /tspublic/v1/metadata/tml/export API endpoint.

Resource URL🔗

POST /tspublic/v1/metadata/tml/export

Request parameters🔗

Form parameter Description Default

Form parameter	Description	Default
`export_ids`	String. JSON array of the IDs of objects to export. An `x-www-form-urlencoded` string containing a JSON array of ids of objects to export. You receive results in the order you request them. For example: To export a single object, `["226abd2843-afef-4c2f-bf2f-8fba065330e"]` To export multiple objects, `["226abd2843-afef-4c2f-bf2f-8fba065330e", ”22d305bc51-688b-414f-badc-94579d48308c”]`	None
`formattype`	String. The format in which to export the objects. Valid values are `JSON` and `YAML`.	`YAML`
`export_associated`	Boolean. Specifies if you would like to export the associated objects. To export the objects associated with the objects specified in `export_ids`, set the value to `true`. When set to `true`, the API exports any underlying worksheets, tables, or views for a given object. By default, the API does not export these underlying objects.	`false`
`export_fqn`	Boolean. When set to `true`, the API exports the FQNs of the referenced objects in the TML data.	`false`
`export_schema_version`	String. Specifies the schema version to use during TML export. By default, the API request uses v1 schema for Worksheets. If you are using Models, set `export_schema_version` to `v2`.	`v1`
`export_dependent`	Boolean. Specifies if the Tables of the referenced Connection object must be included in the export.	`false`
`export_connection_as_dependent`	Boolean. Specifies if a connection object must be included as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard TML. This parameter is considered only when `export_associated` is set to `true` in the API request.	`false`
`all_orgs_override`	Boolean. Specifies if the export request is sent from all Orgs context. Applicable to Orgs-enabled instances only.	`false`

export_ids

String. JSON array of the IDs of objects to export. An x-www-form-urlencoded string containing a JSON array of ids of objects to export. You receive results in the order you request them.

For example:

To export a single object, ["226abd2843-afef-4c2f-bf2f-8fba065330e"]
To export multiple objects, ["226abd2843-afef-4c2f-bf2f-8fba065330e", ”22d305bc51-688b-414f-badc-94579d48308c”]

None

formattype

String. The format in which to export the objects. Valid values are JSON and YAML.

YAML

export_associated

Boolean. Specifies if you would like to export the associated objects. To export the objects associated with the objects specified in export_ids, set the value to true. When set to true, the API exports any underlying worksheets, tables, or views for a given object. By default, the API does not export these underlying objects.

false

export_fqn

Boolean. When set to true, the API exports the FQNs of the referenced objects in the TML data.

false

export_schema_version

String. Specifies the schema version to use during TML export. By default, the API request uses v1 schema for Worksheets. If you are using Models, set export_schema_version to v2.

v1

export_dependent

Boolean. Specifies if the Tables of the referenced Connection object must be included in the export.

false

export_connection_as_dependent

Boolean. Specifies if a connection object must be included as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard TML. This parameter is considered only when export_associated is set to true in the API request.

false

all_orgs_override

Boolean. Specifies if the export request is sent from all Orgs context. Applicable to Orgs-enabled instances only.

false

Example request🔗

Make sure the API request has the following header:

Accept: text/plain

cURL

curl -X POST
--header 'Accept: text/plain' \
--header 'X-Requested-By: ThoughtSpot' \
--data-urlencode 'export_ids=["12289fad-f230-485e-8c65-e36082eebf44"]' \
--data-urlencode 'formattype=JSON' \
--data-urlencode 'export_associated=false' \
--data-urlencode 'export_fqn=true' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/export'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/export

Example response🔗

{
   "object":[
      {
         "info":{
            "name":"Total sales",
            "filename":"Total sales.pinboard.tml",
            "status":{
               "status_code":"OK"
            },
            "type":"pinboard",
            "id":"bf3b1f36-b96e-4aa7-b619-b7743c8bd15c"
         },
         "edoc":"{\"guid\": \"bf3b1f36-b96e-4aa7-b619-b7743c8bd15c\",\"liveboard\": {\"name\": \"Total sales\",\"visualizations\": [{\"id\": \"Viz_1\",\"answer\": {\"name\": \"Total sales by store\",\"tables\": [{\"id\": \"(Sample) Retail - Apparel\",\"name\": \"(Sample) Retail - Apparel\",\"fqn\": \"cd252e5c-b552-49a8-821d-3eadaa049cca\"}],\"search_query\": \"[sales] [store] [state]\",\"answer_columns\": [{\"name\": \"state\"},{\"name\": \"store\"},{\"name\": \"Total sales\"}],\"table\": {\"table_columns\": [{\"column_id\": \"store\",\"show_headline\": false},{\"column_id\": \"state\",\"show_headline\": false},{\"column_id\": \"Total sales\",\"show_headline\": false}],\"ordered_column_ids\": [\"store\",\"state\",\"Total sales\"],\"client_state\": \"\",\"client_state_v2\": \"{\\\"tableVizPropVersion\\\": \\\"V1\\\"}\"},\"chart\": {\"type\": \"GEO_AREA\",\"chart_columns\": [{\"column_id\": \"store\"},{\"column_id\": \"state\"},{\"column_id\": \"Total sales\"}],\"axis_configs\": [{\"x\": [\"state\"],\"y\": [\"Total sales\"]}],\"client_state\": \"\",\"client_state_v2\": \"{\\\"version\\\": \\\"V4DOT2\\\",\\\"chartProperties\\\": {\\\"mapviewport\\\": {\\\"center\\\": [-1.0815372462017208E7,4944187.994859374],\\\"zoomLevel\\\": 5.140063818579165},\\\"responsiveLayoutPreference\\\": \\\"AUTO_ON\\\",\\\"chartSpecific\\\": {}},\\\"axisProperties\\\": [{\\\"id\\\": \\\"be5fe824-1a94-4fc4-88f6-501198708122\\\",\\\"properties\\\": {\\\"axisType\\\": \\\"Y\\\",\\\"linkedColumns\\\": [\\\"Total sales\\\"],\\\"isOpposite\\\": false}},{\\\"id\\\": \\\"474621ab-c78c-496f-aa71-8de82a5a1af4\\\",\\\"properties\\\": {\\\"axisType\\\": \\\"X\\\",\\\"linkedColumns\\\": [\\\"state\\\"]}}],\\\"systemSeriesColors\\\": [{\\\"serieName\\\": \\\"Total sales\\\",\\\"color\\\": \\\"#48D1E0\\\"}],\\\"systemMultiColorSeriesColors\\\": [{\\\"serieName\\\": \\\"Total sales\\\",\\\"colorMap\\\": [{\\\"serieName\\\": \\\"state\\\",\\\"color\\\": [\\\"#ffffb2\\\",\\\"#fddd87\\\",\\\"#fba35d\\\",\\\"#f75534\\\",\\\"#f9140a\\\",\\\"#d70315\\\",\\\"#b10026\\\"]}]}]}\"},\"display_mode\": \"CHART_MODE\"}},{\"id\": \"Viz_2\",\"answer\": {\"name\": \"Total sales by store\",\"tables\": [{\"id\": \"(Sample) Retail - Apparel\",\"name\": \"(Sample) Retail - Apparel\",\"fqn\": \"cd252e5c-b552-49a8-821d-3eadaa049cca\"}],\"search_query\": \"[sales] [store] [quantity purchased]\",\"answer_columns\": [{\"name\": \"store\"},{\"name\": \"Total quantity purchased\"},{\"name\": \"Total sales\"}],\"table\": {\"table_columns\": [{\"column_id\": \"store\",\"show_headline\": false},{\"column_id\": \"Total sales\",\"show_headline\": false},{\"column_id\": \"Total quantity purchased\",\"show_headline\": false}],\"ordered_column_ids\": [\"store\",\"Total sales\",\"Total quantity purchased\"],\"client_state\": \"\",\"client_state_v2\": \"{\\\"tableVizPropVersion\\\": \\\"V1\\\"}\"},\"chart\": {\"type\": \"COLUMN\",\"chart_columns\": [{\"column_id\": \"store\"},{\"column_id\": \"Total sales\"},{\"column_id\": \"Total quantity purchased\"}],\"axis_configs\": [{\"x\": [\"store\"],\"y\": [\"Total sales\",\"Total quantity purchased\"]}],\"client_state\": \"\",\"client_state_v2\": \"{\\\"version\\\": \\\"V4DOT2\\\",\\\"chartProperties\\\": {\\\"responsiveLayoutPreference\\\": \\\"AUTO_ON\\\",\\\"chartSpecific\\\": {}},\\\"axisProperties\\\": [{\\\"id\\\": \\\"6cac31dc-bf75-4e9e-ab96-422053d913cd\\\",\\\"properties\\\": {\\\"axisType\\\": \\\"Y\\\",\\\"linkedColumns\\\": [\\\"Total sales\\\"],\\\"isOpposite\\\": false}},{\\\"id\\\": \\\"5f5971ce-7e5f-48a0-9ba4-2c376699f64c\\\",\\\"properties\\\": {\\\"axisType\\\": \\\"Y\\\",\\\"linkedColumns\\\": [\\\"Total quantity purchased\\\"],\\\"isOpposite\\\": true}},{\\\"id\\\": \\\"23799dc2-3d6c-4da1-9d1b-e1dba0e5cc00\\\",\\\"properties\\\": {\\\"axisType\\\": \\\"X\\\",\\\"linkedColumns\\\": [\\\"store\\\"]}}],\\\"systemSeriesColors\\\": [{\\\"serieName\\\": \\\"Total sales\\\",\\\"color\\\": \\\"#48D1E0\\\"},{\\\"serieName\\\": \\\"Total quantity purchased\\\",\\\"color\\\": \\\"#2E75F0\\\"}],\\\"systemMultiColorSeriesColors\\\": [{\\\"serieName\\\": \\\"Total sales\\\",\\\"colorMap\\\": [{\\\"serieName\\\": \\\"a3882487-1509-4b13-8430-2e91d511a865\\\",\\\"color\\\": [\\\"#ffffb2\\\",\\\"#fddd87\\\",\\\"#fba35d\\\",\\\"#f75534\\\",\\\"#f9140a\\\",\\\"#d70315\\\",\\\"#b10026\\\"]}]}]}\"},\"display_mode\": \"CHART_MODE\"}}]}}"
      }
   ]
}

Response codes🔗

HTTP status code	Description
200	Successful TML export operation
400	Bad request
401	Unauthorized - wrong credentials
403	Forbidden - incorrect permissions
404	Not found
500	Internal server error

HTTP status code

Description

200

Successful TML export operation

400

Bad request

401

Unauthorized - wrong credentials

403

Forbidden - incorrect permissions

404

Not found

500

Internal server error

Export TML objects in bulk🔗

To export TML objects in a batch, use the /tspublic/v1/metadata/tml/export/batch API endpoint. This API operation supports exporting User, User Group, and Role objects only.

Resource URL🔗

POST /tspublic/v1/metadata/tml/export

Request parameters🔗

Form parameter Description Default

Form parameter	Description	Default
`batch_size`	Integer. Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation.	`20`
`batch_offset`	Integer. Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API.	`0`
`metadata_type`	String. Type of the metadata object to export. Use one of the following values: `USER` `USER_GROUP` `ROLE` Applicable to instances on which Role-based access control is enabled.	—None—
`export_dependent`	Boolean. Specify if you want to export the dependent objects. For example, user groups to which user objects are assigned or sub-groups of a user group. However, to get full details of the dependent objects, the API call initiator must have view or edit access to the dependent object.	`false`
`edoc_format`	String. Format of the TML content. You can export TML data in JSON or YAML format.	`JSON`
`all_orgs_override`	Boolen. Specifies if the TML data should be sent from the all Org context.	`false`

batch_size

Integer. Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation.

20

batch_offset

Integer. Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API.

0

metadata_type

String. Type of the metadata object to export. Use one of the following values:

USER
USER_GROUP
ROLE
Applicable to instances on which Role-based access control is enabled.

—None—

export_dependent

Boolean. Specify if you want to export the dependent objects. For example, user groups to which user objects are assigned or sub-groups of a user group. However, to get full details of the dependent objects, the API call initiator must have view or edit access to the dependent object.

false

edoc_format

String. Format of the TML content. You can export TML data in JSON or YAML format.

JSON

all_orgs_override

Boolen. Specifies if the TML data should be sent from the all Org context.

false

Example request🔗

Make sure the API request has the following header:

Accept: text/plain

cURL

curl -X POST
--header 'Accept: text/plain' \
--header 'X-Requested-By: ThoughtSpot' \
--data-urlencode 'export_ids=["12289fad-f230-485e-8c65-e36082eebf44"]' \
--data-urlencode 'formattype=JSON' \
--data-urlencode 'export_associated=false' \
--data-urlencode 'export_fqn=true' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/export'

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: text/plain' \
-d 'batch_size=20&batch_offset=0&metadata_type=USER&export_dependent=false&edoc_format=JSON&all_orgs_override=false' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/export/batch'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/metadata/tml/export/batch

Example response🔗

{
  "data": {
    "result": [
      {
        "info": {
          "name": "TestUserA",
          "id": "54a1dd6f-d201-4be3-8896-6f327ea0b5d9",
          "type": "user",
          "status": {
            "status_code": "OK"
          }
        }
      },
      {
        "info": {
          "name": "TestUserB",
          "id": "1d598cc5-59c6-474b-8c3f-078909650a4a",
          "type": "user",
          "status": {
            "status_code": "OK"
          }
        }
      }
    ],
    "batch_offset": "0",
    "batch_size": 2,
    "isLastBatch": false
  }
}

Response codes🔗

HTTP status code	Description
200	Successful TML export operation
400	Bad request
401	Unauthorized - wrong credentials
403	Forbidden - incorrect permissions
404	Not found
500	Internal server error

HTTP status code

Description

200

Successful TML export operation

400

Bad request

401

Unauthorized - wrong credentials

403

Forbidden - incorrect permissions

404

Not found

500

Internal server error