# REST API v1 - TML API endpoints > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/tml-api-v1 # REST API v1 - TML API endpoints > **IMPORTANT:** The REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints. ## Supported operations The TML API endpoints allow you to programmatically export, validate, and import scriptable [ThoughtSpot Modeling Language (TML)]({{navprefix}}/{{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. | API endpoint | Available from | | --- | --- | | `[**POST** /tspublic/v1/metadata/tml/import]({{navprefix}}/{{tml-api}}#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]({{navprefix}}/{{tml-api}}#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]({{navprefix}}/{{tml-api}}#export)` 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 | | --- | --- | --- | | `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 objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. - `ALL_OR_NONE` Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. - `VALIDATE_ONLY` Validates the objects but does not import them. | `PARTIAL` | | `force_create` _Optional_ | _Boolean_. Specifies if you are updating or creating objects. To create new objects, specify `true`. By default, ThoughtSpot updates the 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 the GUID assigned to a new object created from the TML import, check the `id_guid` property in the response headers. | `false` | | `all_orgs_override` _Optional_ | _Boolean_. Specify if import operation must be run for all Orgs on your instance. _Requires Org administration privileges to access TML objects across all Orgs._ | `false` | | `skip_cdw_validation_for_tables` _Optional_ | _Boolean_. Skips Cloud Data Warehouse validation for table TML imports. | `false` | | `skip_diff_check` _Optional_ | _Boolean_. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. | `false` | ### Example request Make sure the API request has the `Accept: text/plain` header: **cURL** ```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 ```JSON { "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 | ## 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 | | --- | --- | --- | | `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` _Optional_ | _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 Models, Tables, or Views for a given object. By default, the API does not export these underlying objects. | `false` | | `export_fqn` _Optional_ | _Boolean_. When set to `true`, the API exports the FQNs of the referenced objects in the TML data. | `false` | | `export_schema_version` _Optional_ | _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](https://docs.thoughtspot.com/cloud/latest/models), set `export_schema_version` to `v2`. | `v1` | | `export_dependent` _Optional_ | _Boolean_. Specifies if the Tables of the referenced Connection object must be included in the export. | `false` | | `export_connection_as_dependent` _Optional_ | _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` _Optional_ | _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 `Accept: text/plain` header. **cURL** ```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 ```JSON { "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 | ## 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 | | --- | --- | --- | | `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]({{navprefix}}/{{roles}}) 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 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 ```JSON { "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 |