Skip to main content

IMPORTANT - Product End of Life Statement - IMPORTANT

Request RE, Survey, and Calendar 1.5 Support Ending December 31, 2020
Contact Kinetic Data Support with Questions
Kinetic Community

Import Tree

This web method is used to import a tree or local routine from a tree export file.  This API method only supports trees that were exported using the Kinetic Task v4 tree export format.  If you need to import trees that were exported from Kinetic Task v2 or v3, you will need to use the Import Tree form on the Kinetic Task web consoles.  This method is the inverse of the Export Trees web method. The URL for this web method contains the import-tree action.


HTTP Request

Method: POST

URL: /app/api/v1/import-tree

Body Content:

    "structure": "<tree>...</tree>"


Body Content

This web method expects all data to be sent as a JSON formatted string attached as body content, and must contain the structure parameter.  All other parameters are optional, and will override values in the contents of the structure parameter.


Body Parameter Name Description Required / Optional
structure   Required
definitionId   Optional
source   Optional
sourceGroup   Optional
name   Optional
notes   Optional
ownerEmail   Optional
status   Optional
type   Optional



    "structure": "<tree>...</tree>"

In this example, the tree will be imported using all values that were exported with the tree.


Response Messages

A successful API response will contain a 200 response code and a JSON formatted response body.  The JSON response object will contain the following properties:


Response Property Description
message A message describing what Kinetic Task did with the API request.
tree Details about the imported tree.


Example response:

    "message": "Imported the ..."
    "tree": {


A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.


Example of a failed request:

Response Code: 400

Response Body:

    "message": "Malformed tree structure"


Response Codes

Response Code Reason
200 Successful request.
400 If there was a problem importing the tree or local routine.
400 If the required structure body parameter was not provided.
401 If a Basic Authentication header was provided, but the credentials were not valid.
403 If the source has any applied API policy rules, and one or more of the policy rules was violated.
500 If there was an unexpected server error.



Example - Simple

This is a simple example showing how to import a tree, and override the tree name.  This example does not use any authorization, so no headers need to be provided.


Method: POST

URL: /app/api/v1/import-tree

Body Content Parameters:

  1. structure - Playground
  2. name - Playground

​​Body Content:

    "structure": "<tree>...</tree>",
    "name": "Override Tree Name"


This example is attempting to import the tree export file, and then override the name of the tree that is embedded in the export file.


Response Code: 200

Response Body:

    "message": "Imported the \"Playground :: Documentation :: Override Tree Name\" tree",
    "tree": {
        "createdAt": "2014-09-15T17:22:18.554Z",
        "createdBy": "SYSTEM",
        "id": 87,
        "name": "Override Tree Name",
        "notes": "An example tree",
        "ownerEmail": "",
        "source": {
            "name": "Playground"
        "sourceGroup": "Documentation",
        "status": "Active",
        "updatedAt": "2014-09-15T17:22:18.554Z",
        "updatedBy": "SYSTEM"