> ## Documentation Index > Fetch the complete documentation index at: https://docs.cula.tech/llms.txt > Use this file to discover all available pages before exploring further. # Update a machine data annotation ## OpenAPI ````yaml /openapi.json patch /machine-data-annotations/{id} openapi: 3.1.0 info: title: Cula Tracking API version: 0.3.13 servers: - url: https://api.demo.cula.earth/tracking/v1 security: [] tags: - name: Organisations description: '' - name: Sites description: '' - name: Machines description: '' - name: Machine Variables description: '' - name: Machine Data Imports description: '' - name: Machine Data Annotations description: '' - name: Delivery Configs description: '' - name: Deliveries description: '' - name: Material Sourcing Configs description: '' - name: Material Sourcings description: '' - name: Material Conversion Configs description: '' - name: Material Conversions description: '' - name: Material Utilization Configs description: '' - name: Material Utilizations description: '' - name: Material Batches description: '' - name: Material Pools description: '' - name: Material Containers description: '' - name: Sinks description: '' - name: Documents description: '' - name: Webhooks description: '' paths: /machine-data-annotations/{id}: patch: tags: - Machine Data Annotations summary: Update a machine data annotation parameters: - name: Cula-Organisation-Id in: header description: >- ID of the organisation the request operates on behalf of (e.g. `org_...`). Must be an organisation the API client has access to. required: true schema: type: string example: org_01k83mfmhgchya944v86ryvhpq - name: id required: true in: path schema: type: string example: mda_01k7v3n9cbp2s0w8qh4xr6fzje requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchMachineDataAnnotationRequest' examples: text: summary: Replace the text value: text: Kiln stopped for maintenance external_id: summary: Assign an external ID value: external_id: ANNOTATION-EXT-0001 instant: summary: Move an instant value: occurred_at: '2026-05-01T13:00:00Z' range: summary: Move the end of a time range value: ended_at: '2026-05-01T15:00:00Z' responses: '200': description: The updated machine data annotation. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/GetInstantMachineDataAnnotationResponse title: Instant - $ref: '#/components/schemas/GetRangeMachineDataAnnotationResponse' title: Range discriminator: propertyName: type mapping: instant: $ref: >- #/components/schemas/GetInstantMachineDataAnnotationResponse range: $ref: >- #/components/schemas/GetRangeMachineDataAnnotationResponse '400': description: Invalid request payload or parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: The field limit must not be greater than 100. '401': description: Missing or invalid access token. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Invalid or expired token '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found message: >- Resource with ID xyz_01k56g7aec6dt5zrtamc72vw446 could not be found. '409': description: Conflicting resource state. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: conflict message: >- There exists already an object with external ID MY-CUSTOM-ID within this organisation. '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: Internal server error. security: - AccessToken: [] components: schemas: PatchMachineDataAnnotationRequest: type: object properties: text: type: string maxLength: 5000 example: Kiln restarted after the morning inspection description: >- Replaces the free-text note. Must not be blank; surrounding whitespace is trimmed. external_id: type: string example: ANNOTATION-EXT-0001 description: >- 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. nullable: true maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9\-_]+$ occurred_at: type: string format: date-time example: '2026-05-01T12:30:00Z' description: >- New instant of an `instant` annotation as an ISO 8601 timestamp with an explicit UTC offset (`Z` or `±hh:mm`). started_at: type: string format: date-time example: '2026-05-01T12:30:00Z' description: >- 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. ended_at: type: string format: date-time example: '2026-05-01T12:30:00Z' description: >- 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. description: >- 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`. GetInstantMachineDataAnnotationResponse: type: object properties: id: type: string example: mda_01k7v3n9cbp2s0w8qh4xr6fzje description: Unique identifier of the machine data annotation. external_id: type: string nullable: true example: ANNOTATION-EXT-0001 description: The external ID you assigned to this annotation, if any. type: type: string enum: - instant description: Whether the annotation marks a single instant or a time range. occurred_at: type: string format: date-time example: '2026-05-01T12:30:00.000Z' description: The annotated instant as a UTC ISO 8601 timestamp. site: description: The site the annotation belongs to. allOf: - $ref: '#/components/schemas/SiteReference' created_at: type: string format: date-time example: '2026-05-06T19:34:00.000Z' description: Time the annotation was created. text: type: string example: Kiln restarted after the morning inspection description: >- Free-text note describing the annotated event that affected machine data. machine_variables: description: The machine variables the annotation is linked to. type: array items: $ref: '#/components/schemas/MachineVariableReference' required: - id - external_id - type - occurred_at - site - created_at - text - machine_variables GetRangeMachineDataAnnotationResponse: type: object properties: id: type: string example: mda_01k7v3n9cbp2s0w8qh4xr6fzje description: Unique identifier of the machine data annotation. external_id: type: string nullable: true example: ANNOTATION-EXT-0001 description: The external ID you assigned to this annotation, if any. type: type: string enum: - range description: Whether the annotation marks a single instant or a time range. started_at: type: string format: date-time example: '2026-05-01T12:30:00.000Z' description: Start of the annotated time range as a UTC ISO 8601 timestamp. ended_at: type: string format: date-time example: '2026-05-01T14:00:00.000Z' description: End of the annotated time range as a UTC ISO 8601 timestamp. site: description: The site the annotation belongs to. allOf: - $ref: '#/components/schemas/SiteReference' created_at: type: string format: date-time example: '2026-05-06T19:34:00.000Z' description: Time the annotation was created. text: type: string example: Kiln restarted after the morning inspection description: >- Free-text note describing the annotated event that affected machine data. machine_variables: description: The machine variables the annotation is linked to. type: array items: $ref: '#/components/schemas/MachineVariableReference' required: - id - external_id - type - started_at - ended_at - site - created_at - text - machine_variables Error: type: object properties: code: type: string example: bad_request message: type: string example: The field limit must not be greater than 100. required: - code - message SiteReference: type: object properties: id: type: string nullable: true example: ste_01k8g7aec6dt5zrtamc72ww446 external_id: type: string nullable: true example: SITE-EXT-0001 description: >- References a site by its ID and the external ID you assigned to it (if any). required: - id - external_id MachineVariableReference: type: object properties: id: type: string example: mvr_01kae7a2kpkcqwy7fwk2fft11h description: >- The ID of the machine variable. Resolve it via the `/machine-variables` endpoints. description: References a machine variable by its ID. required: - id securitySchemes: AccessToken: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.demo.cula.earth/oauth2/token scopes: {} description: >- OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access. ````