> ## 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. # Create a machine data annotation ## OpenAPI ````yaml /openapi.json post /machine-data-annotations 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: post: tags: - Machine Data Annotations summary: Create 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 requestBody: required: true content: application/json: schema: oneOf: - $ref: >- #/components/schemas/CreateInstantMachineDataAnnotationRequest title: Instant - $ref: '#/components/schemas/CreateRangeMachineDataAnnotationRequest' title: Range discriminator: propertyName: type mapping: instant: $ref: >- #/components/schemas/CreateInstantMachineDataAnnotationRequest range: $ref: >- #/components/schemas/CreateRangeMachineDataAnnotationRequest examples: instant: summary: Annotate an instant value: 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 range: summary: Annotate a time range value: type: range started_at: '2026-05-01T12:30:00Z' ended_at: '2026-05-01T14:00:00Z' text: Kiln restarted after the morning inspection machine_variables: - id: mvr_01kae7a2kpkcqwy7fwk2fft11h site: external_id: SITE-EXT-0001 responses: '201': description: The created 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 '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: CreateInstantMachineDataAnnotationRequest: type: object properties: 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:00Z' description: >- The annotated instant as an ISO 8601 timestamp with an explicit UTC offset (`Z` or `±hh:mm`). text: type: string maxLength: 5000 example: Kiln restarted after the morning inspection description: >- Free-text note describing the annotated event that affected machine data. Must not be blank; surrounding whitespace is trimmed. machine_variables: maxItems: 100 description: >- The machine variables to link the annotation to; all must be available at `site`. May be empty. type: array items: $ref: '#/components/schemas/MachineVariableIdReference' site: description: >- The site the annotation belongs to. Reference it either by its ID or by its external ID, but not both. oneOf: - $ref: '#/components/schemas/SiteIdReference' - $ref: '#/components/schemas/SiteExternalIdReference' 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. nullable: false maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9\-_]+$ required: - type - occurred_at - text - machine_variables - site CreateRangeMachineDataAnnotationRequest: type: object properties: 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:00Z' description: >- Start of the annotated time range as an ISO 8601 timestamp with an explicit UTC offset (`Z` or `±hh:mm`). ended_at: type: string format: date-time example: '2026-05-01T14:00:00Z' description: >- End of the annotated time range as an ISO 8601 timestamp with an explicit UTC offset (`Z` or `±hh:mm`); must lie after `started_at`. text: type: string maxLength: 5000 example: Kiln restarted after the morning inspection description: >- Free-text note describing the annotated event that affected machine data. Must not be blank; surrounding whitespace is trimmed. machine_variables: maxItems: 100 description: >- The machine variables to link the annotation to; all must be available at `site`. May be empty. type: array items: $ref: '#/components/schemas/MachineVariableIdReference' site: description: >- The site the annotation belongs to. Reference it either by its ID or by its external ID, but not both. oneOf: - $ref: '#/components/schemas/SiteIdReference' - $ref: '#/components/schemas/SiteExternalIdReference' 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. nullable: false maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9\-_]+$ required: - type - started_at - ended_at - text - machine_variables - site 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 MachineVariableIdReference: type: object properties: id: type: string example: mvr_01kae7a2kpkcqwy7fwk2fft11h description: References a machine variable by its ID. required: - id SiteIdReference: type: object properties: id: type: string example: ste_01k8g7aec6dt5zrtamc72ww446 description: References a site by its ID. required: - id SiteExternalIdReference: type: object properties: external_id: type: string example: SITE-EXT-0001 nullable: false maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9\-_]+$ description: References a site by the external ID you assigned to it. required: - external_id 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. ````