Skip to main content

Metrics management (/v2/metrics)

Updated over a month ago

This section details the endpoints for creating, listing, modifying, and deleting metrics in the repository.

List and search metrics

Description

This request retrieves a list of metrics, with options to filter and paginate the results.

GET /v2/metrics

Scope

To execute this request, you must have the following scope: metrics:read.

Parameters

  • name (string, optional): Filters metrics whose name contains this string.

  • datasource (string, optional): Filters by a specific datasource.

  • limit (integer, optional): Number of results per page (default: 50).

  • paginationKey (string, optional): Key to get the next page of results (see pagination handling).

  • onlyFormula (boolean, optional): If true, returns only calculated metrics.

These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&":

General syntax of the GET request: .../metrics?datasource=[datasource]&limit=[limit]&name=[name_filter]

Example request

# Command to list the first 2 metrics from the "main" datasource
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics?datasource=main&limit=2' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Responses

Example of a valid response (200 OK) : 

{ 
   "data": [ 
     { 
       "id": "main@cip_50", 
       "name": "cip_50", 
       "datasource": "main", 
       "type": "Raw", 
       "description": "metric description", 
       "unit": "C°" 
     }, 
     { 
       "id": "main@cip_51", 
       "name": "cip_51", 
       "datasource": "main", 
       "type": "Calculated", 
       "description": "formula", 
       "unit": "C°" 
     } 
   ], 
   "paginationInfo": { 
     "count": 2, 
     "isComplete": false, 
     "paginationKey": "[id:main@cip_51]" 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Pagination Handling (isComplete)

Please refer to the section on pagination handling.

Common Errors

Please refer to the list of common errors.

Create a new metric

Description

This request adds a new metric to the repository.

POST /v2/metrics

Scope

To execute this request, you must have the following scope: metrics:admin.

Parameters

These parameters must be included in your request body.

  • name (string, required): Name of the metric (must be unique per datasource).

  • datasource (string, required): Datasource to which the metric belongs.

  • type (string, required): Type of the metric (Raw, Calculated, Manual, System).

  • description (string, optional): Textual description of the metric.

  • unit (string, optional): Unit of measurement for the metric.

  • storageRuleId (uuid, optional): ID of the storage rule to apply.

  • accessZones (array of uuid, optional): List of access zone IDs (authorizations) to apply.

The following parameters must be provided in the request body, in JSON format.

General syntax of the request body

{ 
   "name": "nom_unique_par_datasource", 
   "datasource": "source_de_donnees", 
   "type": "Raw | Calculated | Manual | System", 
   "description": "description_de_la_metrique", 
   "unit": "unite_de_mesure", 
   "storageRuleId": "uuid_regle_stockage", 
   "accessZones": [ "uuid_zone_acces_1" ] 
 }

Request example

# Command to create a new metric
 curl -X POST \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics' \ 
 
   # ----- Headers ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Body ----- 
   -d ' 
   { 
     "name": "test_metric_creation_api", 
     "datasource": "main", 
     "type": "Raw", 
     "description": "Métrique de test créée via API" 
   } 
   '

Responses

Example of a valid response (200 OK) : 

{ 
   "data": { 
     "id": "main@test_api", 
     "name": "test_api", 
     "datasource": "main", 
     "type": "Raw", 
     "storageRule": { 
       "id": "86ca92b1-dc30-4f32-ac78-b8ab4033d6db", 
       "name": "TestRule_V1_bf6d15b9", 
       "deadband": 0, 
       "validityInSecond": 3600, 
       "decimalPrecision": 2, 
       "isDefault": false 
     }, 
     "accessZones": [ 
       { 
         "id": "4e1daf3a-9a1c-4c54-a6ea-f826e03c4270", 
         "name": "#DefaultAccessZoneRead", 
         "accessType": "Read", 
         "isDefault": true 
       } 
     ], 
     "description": "test description", 
     "unitSettings": { 
       "sourceUnit": "m2", 
       "category": "Area", 
       "targetUnit1": "m2", 
       "targetUnit2": "mi2" 
     }, 
     "source": "" 
   }, 
   "resultCode": 1010, 
   "message": "OK" 
 }

Common Errors

Please refer to the list of common errors.

Get metric details

Description

This request retrieves the complete configuration for a single metric using its unique identifier.

GET /v2/metrics/{metricId}

Scope

To execute this request, you must have the following scope: metrics:read.

Parameters

  • metricId (string, required): Unique identifier for the metric in datasource@metricName format.

This request uses a path parameter, which is integrated directly into the URL.

General syntax of the GET request: .../metrics/[datasource]@[metric_name]

Example request

# Command to get the "main@test_metric_f0fb6f7c" metric

curl -X GET 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c' 
 -H 'Authorization: Bearer VOTRE_JETON_JWT'

Responses

Example of a valid response (200 OK) : 

{ 
   "data": { 
     "id": "main@test_metric_f0fb6f7c", 
     "name": "test_metric_f0fb6f7c", 
     "datasource": "main", 
     "type": "Raw", 
     "accessZones": [], 
     "description": "Métrique de test", 
     "unitSettings": {} 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Pagination Handling (isComplete)

Please refer to the section on pagination handling.

Common Errors

Please refer to the list of common errors.

Update a metric

Description

This request updates the configuration of an existing metric.

PUT /v2/metrics/{metricId}

Scope

To execute this request, you must have the following scope: metrics:admin.

Parameters

  • metricId (string, required): Identifier of the metric to update.

This request uses a path parameter, which is integrated directly into the URL.

General URL syntax: .../metrics/[datasource]@[metric_name]

Request Body

The following fields must be provided in the request body, in JSON format. They are identical to those for creating a metric.

  • name (string, required): Name of the metric (must be unique per datasource).

  • datasource (string, required): Datasource to which the metric belongs.

  • type (string, required): Type of the metric (Raw, Calculated, Manual, System).

  • description (string, optional): Textual description of the metric.

  • unit (string, optional): Unit of measurement for the metric.

  • storageRuleId (uuid, optional): ID of the storage rule to apply.

  • accessZones (array of uuid, optional): List of access zone IDs (authorizations) to apply.

General syntax of the request body:

{ 
   "name": "nom_unique_par_datasource", 
   "datasource": "source_de_donnees", 
   "type": "Raw | Calculated | Manual | System", 
   "description": "description_de_la_metrique", 
   "unit": "unite_de_mesure", 
   "storageRuleId": "uuid_regle_stockage", 
   "accessZones": [ "uuid_zone_acces_1" ] 
 }

Request example

# Command to update the description of a metric
 curl -X PUT \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c' \ 
 
   # ----- Headers ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Body ----- 
   -d ' 
   { 
     "name": "test_metric_f0fb6f7c", 
     "datasource": "main", 
     "type": "Raw", 
     "description": "Métrique de test mise à jour" 
   } 
   '

Responses

Example of a valid response (200 OK) : 

{ 
   "data": { 
     "id": "main@test_metric_f0fb6f7c", 
     "name": "test_metric_f0fb6f7c", 
     "datasource": "main", 
     "type": "Raw", 
     "description": "Métrique de test mise à jour", 
     "unitSettings": {} 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Common Errors

Please refer to the list of common errors.

Delete a metric

Description

This request completely deletes a metric and all of its historical values. Warning: this action is irreversible.

DELETE /v2/metrics/{metricId}

Scope

To execute this request, you must have the following scope: metrics:admin.

Parameters

  • metricId (string, required): ID of the metric to delete (datasource@metricName).

This request uses a path parameter, which is integrated directly into the URL.

General syntax of the DELETE request: .../metrics/[datasource]@[metric_name]

Example request

# Command to delete the metric 'main@test_metric_f0fb6f7c_renamed' 
 curl -X DELETE \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c_renamed' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Responses

Example of a valid response (200 OK) : 

{ 
   "statusCode": 1010, 
   "message": "OK" 
 }

Common Errors

Please refer to the list of common errors.

Rename a metric

Description

This request allows you to rename an existing metric. This action should be used with caution.

PUT /v2/metrics/{metricId}/rename

Scope

To execute this request, you must have the following scope: metrics:support.

Parameters

  • metricId (string, required): ID of the metric to be renamed.

  • newName (string, required): The new name for the metric.

This request uses a path parameter, which is integrated directly into the URL.

General URL syntax: .../metrics/[datasource]@[current_metric_name]/rename

Request Body

The newName field must be provided in the request body, in JSON format.

General syntax of the request body:

{ "newName": "new_metric_name" }

Example request

# Command to rename a metric
 curl -X PUT \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c/rename' \ 
 
   # ----- Headers ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Body ----- 
   -d ' 
   { 
     "newName": "test_metric_f0fb6f7c_renamed" 
   } 
   '

Responses

Example of a valid response (200 OK) : 

{ 
   "statusCode": 1010, 
   "message": "OK" 
 }

Common Errors

Please refer to the list of common errors.

Partially update a metric (Patch)

Description

This request allows you to selectively update a metric's configuration, such as its access zones or storage rule, without having to send the entire metric configuration.

PATCH /v2/metrics/{metricId}

Scope

To execute this request, you must have the following scope: metrics:admin.

Parameters

  • metricId (string, required): Unique identifier for the metric in datasource@metricName format.

This request uses a path parameter, which is integrated directly into the URL.

General URL syntax: .../metrics/[datasource]@[metric_name]

Request Body

  • accessZonesId (array of uuid, optional): Replaces the list of access zones associated with the metric with the one provided.

  • storageRuleId (uuid, optional): Changes the storage rule associated with the metric.

The following fields must be provided in the request body, in JSON format. You can provide one or more fields.

General syntax of the request body:

{ 
   "accessZonesId": [ "uuid_zone_1", "uuid_zone_2" ], 
   "storageRuleId": "uuid_de_la_regle_de_stockage" 
 }

Request example

# Command to associate access zones with a metric
 curl -X PATCH \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c' \ 
 
   # ----- Headers ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Body ----- 
   -d ' 
   { 
     "accessZonesId": [ 
       "8f8ccdb5-8918-4710-bbfa-1bb7260f257e", 
       "14567e2c-70a6-41fd-806e-3be66b4129b7" 
     ] 
   } 
   '

Responses

Example of a valid response (200 OK) : 

{ 
   "statusCode": 1010, 
   "message": "OK" 
 }

Common Errors

Please refer to the list of common errors.

Export the metric repository

Description

This request allows you to download the complete metric repository for a datasource into a file, usually in Excel format.

GET /v2/metrics/export/{datasource}

Scope

To execute this request, you must have the following scope: metrics:read.

Parameters

  • datasource (string, required): The datasource whose metric repository should be exported.

This request uses a path parameter, which is integrated directly into the URL.

General syntax of the GET request: .../metrics/export/[datasource]

Example request

# Command to export metrics from the "main" datasource and save the result to a local file.
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/export/main' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -o 'export_metrics.xlsx'

Responses

Example of a valid response (200 OK) :


The response does not contain JSON. The response body is the binary content of the export file (e.g., .xlsx), along with the appropriate HTTP headers (Content-Type and Content-Disposition).

Common Errors

Please refer to the list of common errors.

Import a metric repository

Description

This request allows you to create or update metrics in bulk from a file within a datasource.

POST /v2/metrics/import/{datasource}

Scope

To execute this request, you must have the following scope: metrics:admin.

Parameters

  • datasource (string, required): The datasource into which the metrics from the file will be imported.

This request uses a path parameter, which is integrated directly into the URL.

General syntax of the POST request: .../metrics/import/[datasource]

Request Body

This request must be in multipart/form-data format and contain a single part:

  • file (file, required): The file (usually Excel) containing the metrics to import.

Example request

# Command to import a metric file into the "main" datasource 
 curl -X POST \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/import/main' \ 
 
   # ----- Headers ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: multipart/form-data' \ 
 
   # ----- File to send ----- 
   -F 'file=@/chemin/vers/mon_referentiel.xlsx'

Responses

Example of a valid response (200 OK) :

A 200 OK response with no message body indicates that the import was processed successfully.

Common Errors

Please refer to the list of common errors.

Pagination handling

For performance reasons, when requesting a large number of results (for example, a long list of metrics), the API may divide the response into several "pages". This pagination is managed via the paginationInfo object found in some responses.

  • If isComplete is true: You have received all the data.

  • If isComplete is false: There is more data to retrieve. To get the next page:

    1. Retrieve the value of the paginationKey field from the response you just received.

    2. Make a new request, adding the paginationKey as a parameter with the value you retrieved.

    3. Repeat this process until the final response contains isComplete: true.

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": "Field Required", 
           "message": "The xxx field is required." 
         } 
       ], 
       "statusCode": 1050, 
       "message": "Invalid request" 
     }

  • 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.

Did this answer your question?