curl --request POST \
--url https://api.demo.cula.earth/tracking/v1/machine-data-annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Cula-Organisation-Id: <cula-organisation-id>' \
--data '
{
"type": "instant",
"occurred_at": "2026-05-01T12:30:00Z",
"text": "Kiln restarted after the morning inspection",
"machine_variables": [
{
"id": "mvr_01kae7a2kpkcqwy7fwk2fft11h"
}
],
"site": {
"id": "ste_01k8g7aec6dt5zrtamc72ww446"
},
"external_id": "ANNOTATION-EXT-0001"
}
'{
"id": "mda_01k7v3n9cbp2s0w8qh4xr6fzje",
"external_id": "ANNOTATION-EXT-0001",
"type": "instant",
"occurred_at": "2026-05-01T12:30:00.000Z",
"site": {
"id": "ste_01k8g7aec6dt5zrtamc72ww446",
"external_id": "SITE-EXT-0001"
},
"created_at": "2026-05-06T19:34:00.000Z",
"text": "Kiln restarted after the morning inspection",
"machine_variables": [
{
"id": "mvr_01kae7a2kpkcqwy7fwk2fft11h"
}
]
}{
"code": "bad_request",
"message": "The field limit must not be greater than 100."
}{
"code": "unauthorized",
"message": "Invalid or expired token"
}{
"code": "conflict",
"message": "There exists already an object with external ID MY-CUSTOM-ID within this organisation."
}{
"code": "internal_server_error",
"message": "Internal server error."
}Create a machine data annotation
curl --request POST \
--url https://api.demo.cula.earth/tracking/v1/machine-data-annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Cula-Organisation-Id: <cula-organisation-id>' \
--data '
{
"type": "instant",
"occurred_at": "2026-05-01T12:30:00Z",
"text": "Kiln restarted after the morning inspection",
"machine_variables": [
{
"id": "mvr_01kae7a2kpkcqwy7fwk2fft11h"
}
],
"site": {
"id": "ste_01k8g7aec6dt5zrtamc72ww446"
},
"external_id": "ANNOTATION-EXT-0001"
}
'{
"id": "mda_01k7v3n9cbp2s0w8qh4xr6fzje",
"external_id": "ANNOTATION-EXT-0001",
"type": "instant",
"occurred_at": "2026-05-01T12:30:00.000Z",
"site": {
"id": "ste_01k8g7aec6dt5zrtamc72ww446",
"external_id": "SITE-EXT-0001"
},
"created_at": "2026-05-06T19:34:00.000Z",
"text": "Kiln restarted after the morning inspection",
"machine_variables": [
{
"id": "mvr_01kae7a2kpkcqwy7fwk2fft11h"
}
]
}{
"code": "bad_request",
"message": "The field limit must not be greater than 100."
}{
"code": "unauthorized",
"message": "Invalid or expired token"
}{
"code": "conflict",
"message": "There exists already an object with external ID MY-CUSTOM-ID within this organisation."
}{
"code": "internal_server_error",
"message": "Internal server error."
}Authorizations
OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access.
Headers
ID of the organisation the request operates on behalf of (e.g. org_...). Must be an organisation the API client has access to.
"org_01k83mfmhgchya944v86ryvhpq"
Body
- Instant
- Range
Whether the annotation marks a single instant or a time range.
instant The annotated instant as an ISO 8601 timestamp with an explicit UTC offset (Z or ±hh:mm).
"2026-05-01T12:30:00Z"
Free-text note describing the annotated event that affected machine data. Must not be blank; surrounding whitespace is trimmed.
5000"Kiln restarted after the morning inspection"
The machine variables to link the annotation to; all must be available at site. May be empty.
100Show child attributes
Show child attributes
The site the annotation belongs to. Reference it either by its ID or by its external ID, but not both.
- Option 1
- Option 2
Show child attributes
Show child attributes
A optional custom ID that can be set to an internal ID from your system. This ID must be unique within all objects of the organisation you operate in. You can later use this external ID to reference and query this object. Be aware that you can update this ID later. If you need an immutable ID, use the object ID returned when creating the object.
1 - 100^[A-Za-z0-9\-_]+$"ANNOTATION-EXT-0001"
Response
The created machine data annotation.
- Instant
- Range
Unique identifier of the machine data annotation.
"mda_01k7v3n9cbp2s0w8qh4xr6fzje"
The external ID you assigned to this annotation, if any.
"ANNOTATION-EXT-0001"
Whether the annotation marks a single instant or a time range.
instant The annotated instant as a UTC ISO 8601 timestamp.
"2026-05-01T12:30:00.000Z"
The site the annotation belongs to.
Show child attributes
Show child attributes
Time the annotation was created.
"2026-05-06T19:34:00.000Z"
Free-text note describing the annotated event that affected machine data.
"Kiln restarted after the morning inspection"
The machine variables the annotation is linked to.
Show child attributes
Show child attributes
Was this page helpful?