curl --request PATCH \
--url https://api.demo.cula.earth/tracking/v1/machine-data-annotations/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Cula-Organisation-Id: <cula-organisation-id>' \
--data '
{
"text": "Kiln stopped for maintenance"
}
'{
"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": "not_found",
"message": "Resource with ID xyz_01k56g7aec6dt5zrtamc72vw446 could not be found."
}{
"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."
}Machine Data Annotations
Update a machine data annotation
PATCH
/
machine-data-annotations
/
{id}
curl --request PATCH \
--url https://api.demo.cula.earth/tracking/v1/machine-data-annotations/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Cula-Organisation-Id: <cula-organisation-id>' \
--data '
{
"text": "Kiln stopped for maintenance"
}
'{
"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": "not_found",
"message": "Resource with ID xyz_01k56g7aec6dt5zrtamc72vw446 could not be found."
}{
"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.
Example:
"org_01k83mfmhgchya944v86ryvhpq"
Path Parameters
Example:
"mda_01k7v3n9cbp2s0w8qh4xr6fzje"
Body
application/json
Replaces the given fields and keeps the others. At least one field must be provided. The type of an annotation cannot be changed: an instant only accepts occurred_at, a range only started_at and ended_at.
Replaces the free-text note. Must not be blank; surrounding whitespace is trimmed.
Maximum string length:
5000Example:
"Kiln restarted after the morning inspection"
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. Pass null to remove it.
Required string length:
1 - 100Pattern:
^[A-Za-z0-9\-_]+$Example:
"ANNOTATION-EXT-0001"
New instant of an instant annotation as an ISO 8601 timestamp with an explicit UTC offset (Z or ±hh:mm).
Example:
"2026-05-01T12:30:00Z"
New start of a range annotation as an ISO 8601 timestamp with an explicit UTC offset (Z or ±hh:mm); the range must still end after it starts.
Example:
"2026-05-01T12:30:00Z"
New end of a range annotation as an ISO 8601 timestamp with an explicit UTC offset (Z or ±hh:mm); the range must still end after it starts.
Example:
"2026-05-01T12:30:00Z"
Response
The updated machine data annotation.
- Instant
- Range
Unique identifier of the machine data annotation.
Example:
"mda_01k7v3n9cbp2s0w8qh4xr6fzje"
The external ID you assigned to this annotation, if any.
Example:
"ANNOTATION-EXT-0001"
Whether the annotation marks a single instant or a time range.
Available options:
instant The annotated instant as a UTC ISO 8601 timestamp.
Example:
"2026-05-01T12:30:00.000Z"
The site the annotation belongs to.
Show child attributes
Show child attributes
Time the annotation was created.
Example:
"2026-05-06T19:34:00.000Z"
Free-text note describing the annotated event that affected machine data.
Example:
"Kiln restarted after the morning inspection"
The machine variables the annotation is linked to.
Show child attributes
Show child attributes
Was this page helpful?