This section details the endpoints for creating, listing, modifying, and deleting annotations on specific data points.
List annotations for a metric
Description
This request allows you to retrieve all annotations associated with a metric over a given period.
GET /v2/annotations
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
datasource (string, required): Datasource of the metric.
metricName (string, required): Name of the concerned metric.
start (date-time, optional): Start date of the search period.
end (date-time, optional): End date of the search period.
timezone (string, optional): Time zone for the search (default: Europe/Paris).
paginationKey (string, optional): Key to get the next page of results, provided by the previous response.
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: .../annotations?datasource=[datasource]&metricName=[metric_name]&start=[start_date]&end=[end_date]
Example request
# Command to list annotations for "metric4test_ok" over a 5-minute period
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations?datasource=main&metricName=metric4test_ok&start=2025-06-26T08:01:16Z&end=2025-06-26T08:06:16Z' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Example of a valid response (200 OK):
{
"data": [
{
"id": "cbbf298c-4599-4c25-8cb2-b17c62220767",
"timestamp": "2025-06-26T10:03:46+02:00",
"value": "Valeur mise à jour.",
"isAuthor": true,
"valueUpdate": {
"oldValue": 10.5,
"newValue": 10.6
},
"userName": "Christophe Holmes",
"created": "2025-06-26T10:05:48+02:00"
}
],
"paginationInfo": {
"count": 1,
"isComplete": true
},
"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.
Add an annotation to a data point
Description
This request allows you to create a new annotation and associate it with an existing data point, identified by its exact timestamp.
POST /v2/annotations
Scope
To execute this request, you must have the following scope: metrics:read.
Request Body
name (string, required): Name of the metric to annotate.
datasource (string, optional): Datasource of the metric.
timestamp (date-time, required): The exact timestamp of the data point to annotate.
annotation (string, optional): The text content of the annotation (max 250 characters).
The following parameters must be provided in the request body, in JSON format.
General syntax of the request body:
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point",
"annotation": "votre_texte_d_annotation"
}
Request example
# Command to add an annotation
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations' \
# ----- Headers -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z",
"annotation": "Annotation de test"
}
'
Responses
Example of a valid response (200 OK):
{
"data": {
"id": "e0f5d990-55a1-4c4d-9e09-c8b6555072ad",
"timestamp": "2025-07-01T13:00:50+02:00",
"value": "test_api",
"isAuthor": true,
"userName": "André Matos Calhau",
"created": "2025-07-01T13:55:05+02:00"
},
"resultCode": 1010,
"message": "OK"
}
Common Errors
Please refer to the list of common errors.
Update an annotation
Description
This request allows you to modify the content of an existing annotation, identified by its ID.
PUT /v2/annotations/{id}
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
id (uuid, required): Unique identifier of the annotation to modify.
This request uses a path parameter, which is integrated directly into the URL.
General URL syntax: .../annotations/[annotation_uuid]
Request Body
The fields are the same as for creating an annotation (POST /v2/annotations).
General syntax of the request body:
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point",
"annotation": "votre_nouveau_texte_d_annotation"
}
Example request
# Command to update the annotation with the ID 'cbbf298c-...'
curl -X PUT \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations/cbbf298c-4599-4c25-8cb2-b17c62220767' \
# ----- Headers -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z",
"annotation": "Annotation mise à jour !"
}
'
Responses
Example of a valid response (200 OK) :
{
"resultCode": 1010,
"message": "OK"
}
Common Errors
Please refer to the list of common errors.
Delete an annotation
Description
This request deletes an existing annotation, identified by its ID.
DELETE /v2/annotations/{id}
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
id (uuid, required): Unique identifier of the annotation to delete.
This request uses a path parameter, which is integrated directly into the URL.
General URL syntax: .../annotations/[annotation_uuid]
Request Body
name (string, required): Name of the concerned metric.
datasource (string, optional): Datasource of the metric.
timestamp (string, required): The exact timestamp of the concerned data point.
These fields must be provided in the request body, in JSON format.
General syntax of the request body:
{
"name": "nom_de_la_metrique",
"datasource": "source_de_donnees",
"timestamp": "date_et_heure_iso_du_point"
}
Request example
# Command to delete the annotation with the ID 'cbbf298c-...'
curl -X DELETE \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/annotations/cbbf298c-4599-4c25-8cb2-b17c62220767' \
# ----- Headers -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body -----
-d '
{
"name": "metric4test_ok",
"datasource": "main",
"timestamp": "2025-06-26T08:05:14Z"
}
'
Responses
Example of a valid response (200 OK) :
{
"resultCode": 1010,
"message": "OK"
}
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
isCompleteis true: You have received all the data.If
isCompleteis false: There is more data to retrieve. To get the next page:Retrieve the value of the
paginationKeyfield from the response you just received.Make a new request, adding the
paginationKeyas a parameter with the value you retrieved.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
errorsarray 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.