> ## 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.

# Import machine data



## OpenAPI

````yaml /openapi.json post /machine-data-imports
openapi: 3.1.0
info:
  title: Cula Tracking API
  version: 0.3.10
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: 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-imports:
    post:
      tags:
        - Machine Data Imports
      summary: Import machine data
      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:
              $ref: '#/components/schemas/MachineDataImportRequest'
      responses:
        '201':
          description: The machine data items were ingested successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachineDataImportResponse'
        '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:
    MachineDataImportRequest:
      type: object
      properties:
        type:
          description: Import mode. Only `sync` is currently supported.
          example: sync
          allOf:
            - $ref: '#/components/schemas/MachineDataImportType'
        external_id:
          type: string
          example: MY-IMPORT-ID
          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\-_]+$
        items:
          minItems: 1
          maxItems: 200
          description: Machine data items to ingest. Between 1 and 200 items per request.
          type: array
          items:
            $ref: '#/components/schemas/MachineDataItem'
      required:
        - type
        - items
    MachineDataImportResponse:
      type: object
      properties:
        id:
          type: string
          example: mdi_01knwph011nqfnv5frjh3e32wq
          description: Unique identifier of the machine data import.
        type:
          example: sync
          description: Import mode the request was processed with.
          allOf:
            - $ref: '#/components/schemas/MachineDataImportType'
        item_count:
          type: number
          example: 1
          description: Number of machine data items in the import.
        external_id:
          type: string
          nullable: true
          example: MY-IMPORT-ID
          description: The external ID you assigned to this import (if any).
        created_at:
          type: string
          format: date-time
          example: '2025-10-25T13:02:52.932Z'
          description: When the import was recorded.
      required:
        - id
        - type
        - item_count
        - external_id
        - created_at
    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
    MachineDataImportType:
      type: string
      enum:
        - sync
      description: Import mode. Only `sync` is currently supported.
    MachineDataItem:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: >-
            Measurement timestamp. ISO-8601 date-time with an explicit UTC
            offset (`Z` or `±hh:mm`), up to millisecond precision.
          example: '2025-10-25T13:02:52.932+02:00'
        machine_variable_id:
          type: string
          example: mvr_01kae7a2kpkcqwy7fwk2fft11h
          description: The machine variable this value belongs to.
        value:
          oneOf:
            - type: number
            - type: boolean
          description: >-
            Raw measured value. The server applies the machine variable's factor
            and validates it against the variable's `value_type`. Boolean values
            (or 0/1) are accepted for boolean-typed variables.
          example: 33.3
      required:
        - timestamp
        - machine_variable_id
        - value
  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.

````