This section describes the API endpoints for creating, listing, searching, modifying, and deleting elements of your functional trees.

Reminder: An "item" is an element contained in your tree. It can be a folder or a metric.

Export the elements of a tree structure

Description

This query allows you to download a list of the different types of elements present in a tree structure.

Get v2/data-structures/{data_structure_id}/export

Scope

To perform this request, you must have the scope metadata:read.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.

This parameter must be added to the URL to construct the query string:

/v2/data-structures/{data_structure_id}/export

Request example

# Command to export the elements of a tree structure  
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/export' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Export the elements of a tree structure in flat format

Description

This query allows you to download the complete referential of a tree structure in a "plate" form (a simple list).

GET /v2/data-structures/{data_structure_id}/export/tree

Scope

To perform this request, you must have the scope metadata:read.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.

This parameter must be added to the URL to construct the query string:

/v2/data-structures/{data_structure_id}/export/tree

Request example

# Command to export the elements of a tree structure (flat format)
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/export/tree' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Import a tree structure from an excel file

Description

This query allows you to import the content of a tree structure from an Excel file.

GET /v2/data-structures/{data_structure_id}/export/tree

Note : The import file must follow a defined structure. If you are not familiar with this feature, see the article on importing/exporting a functional tree.

Scope

To perform this request, you must have the scope metadata:admin.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.

This parameter must be added to the URL to construct the query string:

/v2/data-structures/{data_structure_id}/import

Request example

# Command to import the content of a tree structure from a file  
 curl -X 'POST' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/66731055-a2f2-4890-8212-217f7d653d01/import' \ 
 
   # ----- Headers ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: multipart/form-data' \ 
 
   # ----- File to send ----- 
   -F 'file=@/chemin/vers/DemoGTB-2025-07-16.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

Responses

Example of a valid response (200 ok) :

{ 
   "resultCode": 2010, 
   "message": "OK" 
 }

Common errors

Please refer to the list of common errors.

Specific 400 error

If the file is not valid, the following error will appear :

{ 
   "errors": [], 
   "resultCode": 2122, 
   "message": "Type is used" 
 }

List the elements of a tree structure

Description

This query returns the list of all the elements in a tree, including for each their respective information and notably their identifiers (ID), which are necessary for other queries.

Get /v2/data-structures/{data_structure_id}/items

Note: The import file must follow a defined structure. If you are not familiar with this feature, see the article on importing/exporting a functional tree.

Scope

To perform this request, you must have the scope metadata:read.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.

The following parameters allow to apply a filter on the search:
typeId (string, optional): Filters the results to return only elements associated with a specific type, identified by its ID.
isMetric (boolean, optional): Allows filtering elements based on their type (whether it is a metric type or not) can take two values (true or false).
displayParents (boolean, optional): allows to indicate if one wishes to display the parents of each element in the response. can take two values (true or false).
paginationKey (string, optional): Key to obtain the following results page (see pagination management)
limit (integer, optional): limit of results to display

In addition to these filters, a "query" parameter is available to allow you to build a more precise filtering expression. Its specific syntax and search functions are detailed below.
To build your expression, you have:
- logical and comparison operators
- search functions

Liste des opérateurs disponibles :

Comparison :

Description	Syntax
Equals to	==
Different from	!=
Higher than	>
Lower than	<
Higher or equal than	>=
Lower or equal than	<=

Logical :

Operator "AND"	&&
Operator "OR"	\|\|

Search functions to be used

To create your expression in the "query" field, you must use the following search functions.Search functions to be used

searchProperty([parent type], [property name to be checked])

This function filters elements based on the properties of one of their parents in the tree. It will only return items whose parent matches the criteria you specify.

type_id (string | uuid, mandatory): The identifier or type name of the parent you are targeting.
property_name_name (string, mandatory): The property name of the parent you want to check.

. contains("value")

This method applies to a property of the searched element and checks if its value contains the specified string.

We will therefore have [property name of the searched item]. contains("value")

.StartsWith("value")

This method applies to a property of the searched element and checks if its value starts with the specified string.

We will therefore have [property name of the searched element]. StartsWith("value")

.EndsWith("value")

This method applies to a property of the searched element and checks if its value ends with the specified string.

We will therefore have [property name of the searched element]. EndsWith("value")

Example of an expression to put in "query":

We want to retrieve the elements of the tree that meet the following two conditions:

- They must have a parent of type "08fcddd6-5951-4f06-a3df-fd9eea1bb8a3" whose property "test_propriete" is set to "Pau".

- Their own property unit must contain the letter "c".

Request to be indicated:

searchProperty("08fcddd6-5951-4f06-a3df-fd9eea1bb8a3", "test_propriete") == "Pau" && unit.contains("c")

Decomposition:

searchProperty("08fcddd6-5951-4f06-a3df-fd9eea1bb8a3", "test_propriete") == "Pau" : This condition indicates that one wishes to have the elements having a parent with the indicated type and the correct value for the property "test_propriete".

&& : The "AND" operator to add an additional condition.

unit.contains("c"): This part filters the previous results to keep only those whose property "unit" contains the letter "c".

These parameters must be added to the URL to construct the query string:

/v2/data-structures/{data_structure_id}/items? isMetric=[]&displayParents=[]&limit[]&query=[]

Request example

# Command to search for elements that have a parent of type "Silot" with the property "test_propriete" equal to "Pau" # - AND whose unit contains the letter "c".  
 
curl -X 'GET' \ 
  'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items?isMetric=true&displayParents=false&limit=50&query=searchProperty("Silot", "test_propriete") = "Pau" and unit.contains("c")' \ 
 
  # ----- Headers ----- 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer VOTRE_JETON_JWT'

Responses

Example of a valid response (200 ok) :

{ 
   "data": [ 
     { 
       "id": "3d24ece8-d815-4e2a-a31d-9c34cbc29035", 
       "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
       "typeId": "21c4451d-4a20-4ebc-9667-fb29e73825fa", 
       "parentId": "batiments-elementaire", 
       "label": "nj26uv_temperature_elementaire", 
       "metric": { 
         "id": "main@nj26uv_temperature_elementaire", 
         "name": "nj26uv_temperature_elementaire", 
         "datasource": "main", 
         "unit": "°C", 
         "type": "Raw" 
       }, 
       "options": { 
         "indabaId": "main@nj26uv_temperature_elementaire", 
         "indabaLabel": "Name" 
       }, 
       "isTypeMetric": true, 
       "hasError": false 
     } 
   ], 
   "paginationInfo": { 
     "count": 1, 
     "total": 1, 
     "isComplete": true 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Pagination management

For performance reasons, when you request data over a long period, the API may return the results in several parts. Some responses include a boolean field named isResponseComplete to handle this.

If isResponseComplete is true: You have received all the data for the requested period.
If isResponseComplete is false: There is more data to retrieve. To get the next part, you must make a new request with adjusted parameters:
1. Get the timestamp of the last data point received.
2. Make an identical request, but use this timestamp as the new start date (Start).
3. Repeat this process until the response contains isResponseComplete: true.

Common errors

Please refer to the list of common errors.

Add a new item into the functional tree

Description

This request allows you to add a new element within a functional tree.

Post v2/data-structures/{data_structure_id}/items

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.

This parameter must be added to the URL to construct the query string :

/v2/data-structures/{data_structure_id}/items

Request body

Depending on the item you want to create, the request body will include different fields.

Fields common to all elements :

id : identifier of the new element.

Note: If you leave this field blank, an automatic identifier will be generated.
typeId : ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.
label : display name of the new element in the tree structure
properties : if the chosen type contains properties, you can assign a value to these properties in the request body. See the examples below.

example :

{

"id": "F0",

"typeId": "63c80ffc-321e-4a4d-ab44-c643c4ff156d",

"label": "France",

"properties": {

"name": "name country",

"description": "description country",

"hasDescription": true,

"count": 12

}

Specific fields :

If you want to create an element with one (or more) parent(s) in the tree
- parentId : parent element id.
  You can find the identifier of an item with the GET request /v2/data-structures/{data_structure_id}/items or when creating a new item.

{

"id": "R0",

"typeId": "f33d478f-04e9-4613-b094-74df6c62abcb",

"parentId": "F0",

"label": "Region",

"properties": {

"name": "name region"

}

if you want to create an element of metric type
- options:
  - indabaId: indaba identifier of the metric (datasource@name)
  - IndabaLabel: name of the metric

{

"typeId": "6975832e-34f3-42e3-aedb-b16f5802f89a",

"parentId": "XXXXXXX",

"options": {

"indabaId": "datasource@name",

"indabaLabel": "Name"

}

Request example

# Command to create a new item
 curl -X 'POST' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items' \ 
 
   # ----- Headers ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Request body ----- 
   -d ' 
   { 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "doc", 
     "properties": { 
       "test_propriete": "valeur2" 
     } 
   } 
   '

Response

Example of a valid response (200 ok) :

{ 
   "data": { 
     "id": "_doc", 
     "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "doc", 
     "properties": { 
       "test_propriete": "valeur2" 
     }, 
     "isTypeMetric": false, 
     "hasError": false 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Common errors

Please refer to the list of common errors.

Update an existing item

Put /v2/data-structures/{data_structure_id}/items/{item_id}

Scope

To make this request, you must have the scope metadata:admin.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.
type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.

These parameters must be added to the URL to construct the query string :

v2/data-structures/{data_structure_id}/items/{item_id}

Request body

The request body is similar to adding a new item.

Request example

# Command to update an existing element in a data structure  
 curl -X 'PUT' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items/batiments-elementaire' \ 
 
   # ----- Headers ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Request body ----- 
   -d ' 
   { 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "label_modif", 
     "properties": { 
       "name": "name country", 
       "description": "description country", 
       "hasDescription": true, 
       "count": 12 
     } 
   } 
   '

Response

Example of a valid response (200 ok) :

{ 
   "data": { 
     "id": "batiments-elementaire", 
     "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "label_modif", 
     "properties": {}, 
     "isTypeMetric": false, 
     "hasError": false 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Common errors

Please refer to the list of common errors.

Delete an item from a tree structure

This query deletes an item and all its descendants in the tree.

Warning, this action is irreversible.

DELETE /v2/data-structures/{data_structure_id}/items/{item_id}

Scope

To make this request, you must have the scope metadata:admin.

Parameters

data_structure_id (string, required): ID of the tree. This ID can be retrieved via the GET v2/data-structures request or from the response when creating a new tree with POST v2/data-structures.
type_id (string, required): ID assigned to the element type.
This ID can be retrieved via the GET request /v2/data-structures/{data_structure_id}/types or following the creation of a new type with Post v2/data-structures/{data_structure_id}/types.

These parameters must be added to the URL to construct the query string :

v2/data-structures/{data_structure_id}/items/{item_id}

Request example

# Command to delete a specific item from a tree
 curl -X 'DELETE' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/items/_sited' \ 
 
   # ----- Headers ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Response

Example of a valid response (200 ok) :

{ 
   "resultCode": 2010, 
   "message": "OK" 
 }

Common errors

Please refer to the list of common errors.

Common Errors

You will primarily encounter the following HTTP error codes:

400 Bad Request: Your request is malformed. This may be due to a missing parameter, an incorrect data type, or invalid JSON. The response body will contain an errors array detailing the problem.

{ 
"errors": [ 
{ 
"error": "Type_De_L_Erreur", 
"message": "Description détaillée de l'erreur spécifique." 
} 
], 
"statusCode": 1050, 
"message": "Invalid request" 
}

401 Unauthorized: Your authentication token (JWT) is missing, invalid, or expired. You must obtain a new valid token.
403 Forbidden: Your authentication token is valid, but you do not have the necessary rights for this action. This can happen for two reasons:
- Your token does not have the required scope (e.g., you are trying to write data without the metrics:write scope).
- Your token has the correct scope, but your user (or service account) is not linked to an authorization that grants access to the requested metric.
404 Not Found: The resource you are trying to reach does not exist. This typically occurs if you are using an incorrect ID or requesting a metric that does not exist.

Items management

Export the elements of a tree structure

Description

Scope

Parameters

Request example

Export the elements of a tree structure in flat format

Description

Scope

Parameters

Request example

Import a tree structure from an excel file

Description

Scope

Parameters

Request example

Responses

Common errors

Specific 400 error

List the elements of a tree structure

Description

Scope

Parameters

Search functions to be used

Request example

Responses

Pagination management

Common errors

Add a new item into the functional tree

Description

Parameters

Request body

Fields common to all elements :

Specific fields :

Request example

Response

Common errors

Update an existing item

Scope

Parameters

Request body

Request example

Response

Common errors

Delete an item from a tree structure

Scope

Parameters

Request example

Response

Common errors

Common Errors