Skip to main content
The Cula Tracking API separates data into two layers:
  • Config layer — defines fields, types, units, and validation rules.
  • Runtime layer — stores tracking data created during operations.
Configs are managed in the Cula platform and are read-only in v1 of the API. Read them with GET endpoints, then reference them when creating runtime resources.

​
Config versioning

Tracking requirements change over time: data points are added, formulas change, units are updated, or standards require new evidence fields. Each config keeps a version chain so existing data remains tied to the rules used when it was created. Each config has a stable root ID (e.g. stc_01kqzcjrpxf27tge33jwvjhkff) and a chain of versions. The active version is the latest published one. Common reasons for a new version:
  • New data points — a previously untracked measurement becomes required (e.g. adding a moisture content field to a sourcing step).
  • Changed calculations — a computed data point’s formula is updated (e.g. switching from a simple weight conversion to a density-adjusted calculation).
  • Value drift correction — recalibrating thresholds or conversion factors so that computed values stay accurate over time.
  • Regulatory or standard changes — a carbon credit methodology update requires capturing additional evidence fields.
When you create a runtime resource, provide config_id (the root ID). The server resolves it to the active version. Version pinning is not supported in v1. The response includes config_version_id, so every runtime resource records the config version that defined its data shape and calculations at creation time.

​
Config types

Config types mirror runtime types:
Config typeRuntime type
Material sourcing configMaterial sourcing step
Material processing configMaterial processing step
Material application configMaterial application step
Delivery configDelivery
Periodic emission log configEmission log
Each delivery config also declares a direction (incoming or outgoing). Deliveries created from a config inherit the direction — there is no separate “incoming delivery” or “outgoing delivery” resource type.

​
Embedded data point configs

Each config version includes a data_point_configs[] array describing the data points expected for that config. Each data point config has its own stable ID, a type (number, text, amount, etc.), and metadata like the expected unit or label. Two fields drive what you need to send:
  • is_mandatory — the data point must be provided to complete the resource. If it has a default_input_value, the server fills it in when omitted.
  • accepts_input — whether you can submit a value. Data points with accepts_input: false are server-computed and read-only.
For nested resources (deliveries with legs and payload, steps with input/output containers), the config structure mirrors the request body — each level that carries data_points at runtime has a corresponding data_point_configs[] in the config version. See data point nesting structure for the full config-to-runtime mapping.

​
Discovery workflow

Integration flow:
  1. Read config versions — call the config endpoint for your resource type (e.g. GET /v1/material-sourcing-configs/{id} for sourcing steps, or the equivalent for processing, application, deliveries, and emission logs) to discover the active version and its embedded data_point_configs[].
  2. Identify required data points — inspect is_mandatory and accepts_input on each data point config. Include all mandatory, inputtable data points in your request. For configs with nested levels (e.g. a delivery config’s payload_config.data_point_configs[]), apply the same check at each level.
  3. Build your field mapping — map each data_point_config to the corresponding field in your system based on name, type, and unit.
  4. Create runtime resources — use the stable config_id (the root config ID) and the discovered data_point_config IDs when submitting data.
# Read the active version of a material sourcing config and its data points
curl https://api.demo.cula.earth/tracking/v1/material-sourcing-configs/stc_01kqzcjrpxf27tge33jwvjhkff \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID"
If the config is updated in the Cula platform after you build your mapping, new data point configs may appear. Periodically re-read the config to stay in sync.