Skip to main content

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.

Machine data is time-series sensor readings from physical equipment. Cula separates config-time resources (what can be measured) from runtime data (actual readings).

​
Config hierarchy

Three read-only resources define what you can ingest. Cula manages them and exposes them through the API.

​
Machine

A physical device at a site, such as a pyrolysis reactor or truck scale. 
{
  "id": "mch_01kqzcjrpyf27tge6smsbnhkh5",
  "name": "Truck Scale",
  "site": { "id": "ste_01kqzcjrpxf27tge33jwvjhkff" }
}
List machines with GET /machines. Filter by site.

​
Measurement

A group of related sensors on a machine, such as “Rawgas Upgrade 1 Flow Rates”. 
{
  "id": "msr_01kqzcjrpyf27tge77evmjmnqw",
  "name": "Rawgas Upgrade 1 Flow Rates",
  "site": { "id": "ste_01kqzcjrpxf27tge33jwvjhkff" },
  "machine": { "id": "mch_01kqzcjrpyf27tge6smsbnhkh5" }
}
List measurements with GET /measurements. Filter by site or machine.

​
Machine data point config

A metric definition. Declares the unit and factor applied to raw values during ingestion. 
{
  "id": "mdp_01kqzcjrpyf27tge9dnvsqv8t2",
  "name": "retentate outlet flow rate",
  "unit": "m3/h",
  "factor": 1,
  "site": { "id": "ste_01kqzcjrpxf27tge33jwvjhkff" },
  "machine": { "id": "mch_01kqzcjrpyf27tge6smsbnhkh5" },
  "measurement": { "id": "msr_01kqzcjrpyf27tge77evmjmnqw" }
}
List configs with GET /machine-data-point-configs. Filter by site, machine, or measurement.
Machines, measurements, and machine data point configs are platform-managed. They use server-assigned TypeIDs only; external IDs are not supported.

​
Runtime ingestion

At runtime, you ingest machine data items: timestamped values linked to a machine data point config.

​
Data shape

Each item contains: 
{
  "timestamp": "2025-10-25T13:02:52.932+02:00",
  "machine_data_point_config_id": "mdp_01kqzcjrpyf27tge9dnvsqv8t2",
  "value": 33.3
}
FieldTypeDescription
timestampstring (ISO-8601)Measurement time with UTC offset and millisecond precision.
machine_data_point_config_idstringTypeID of the related machine data point config.
valuenumberRaw measured value. The server applies the config’s factor.

​
Ingestion semantics

​
Duplicates and corrections

The tuple (machine_data_point_config_id, timestamp) identifies a stored value. Sending another value with the same tuple replaces the previous one. No correction history is retained. To correct or re-send data, send the correct value at the original timestamp.

​
Late arrival and backfill

Out-of-order data is ingested normally. Dependent logic (aggregations, threshold evaluations, derived calculations) retries until enough data is available. Callers do not need special ordering.

​
Ingestion paths

PathUse caseLimit
MQTT streamingContinuous real-time ingestion from PLCs and gateways-
POST /machine-data/batchSynchronous HTTP ingestion200 items per request
POST /machine-data/import-jobsAsync file upload for large backfills128 MB per file

​
MQTT streaming

Use MQTT for high-frequency continuous streams. Connect over TLS and publish metrics to structured topics. See MQTT streaming for connection details and wire format.

​
HTTP batch

Use HTTP batch for moderate volumes. Items are validated and written atomically. Returns 201 on success.

​
Import jobs

Upload a JSON file for asynchronous processing. The endpoint returns a job ID immediately (202 Accepted). Poll the job for progress.
  • Retried automatically on internal server errors.
  • Not retried if the file has schema or validation errors. The job transitions to failed immediately.

​
Best practices

  • For corrections, re-send the value at the original timestamp.
  • For real-time streams, prefer MQTT. For historical backfills, use import jobs.
  • Always include explicit timezone offsets in timestamps to avoid ambiguity.
  • Reference machine data point configs by TypeID (mdp_...). They are platform-managed and do not support external IDs.