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.

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 execution
Material processing configMaterial processing step execution
Material application configMaterial application step execution
Incoming delivery configIncoming delivery
Outgoing delivery configOutgoing delivery
Periodic emission log configEmission log

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

​
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. Build your field mapping — map each data_point_config to the corresponding field in your system based on name, type, and unit.
  3. Create runtime resources — use the stable config_id (the root config ID) and the discovered data_point_config IDs when submitting data.
# 1. Discover config and its data points
curl https://api.cula.tech/tracking/v1/material-sourcing-configs/stc_01kqzcjrpxf27tge33jwvjhkff \
  -H "Authorization: Bearer $API_KEY"

# 2. Create a runtime resource using the stable config_id
curl -X POST https://api.cula.tech/tracking/v1/material-sourcing \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "stc_01kqzcjrpxf27tge33jwvjhkff",
    "site": { "external_id": "MY-SITE-001" },
    "data_points": [
      { "config_id": "dpc_01abc...", "input_value": { "value": 500, "unit": "kg" } }
    ]
  }'
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.

​
Request body schema

Each config version includes a schema field containing a JSON Schema (draft 2020-12) that describes the expected request body shape for creating a runtime resource. The schema encodes two things that the flat data_point_configs[] list alone cannot express:
  • Nesting structure — which data points belong at which level (e.g. delivery-level vs leg-level vs payload container-level).
  • Required data points per level — via the x-required-config-ids extension on each data_points array.

​
How it works

A delivery config version might include a schema like this: 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["config_id", "issuing_site", "legs", "payload"],
  "properties": {
    "data_points": {
      "type": "array",
      "x-required-config-ids": ["dpc_lot_id...", "dpc_scale_ticket..."]
    },
    "legs": {
      "type": "array",
      "minItems": 1,
      "items": {
        "properties": {
          "data_points": {
            "type": "array",
            "x-required-config-ids": []
          }
        }
      }
    },
    "payload": {
      "type": "array",
      "minItems": 1,
      "items": {
        "properties": {
          "data_points": {
            "type": "array",
            "x-required-config-ids": ["dpc_weight_gross...", "dpc_weight_net..."]
          }
        }
      }
    }
  }
}
The x-required-config-ids array lists the config_id values from data_point_configs that must appear in that specific data_points array. Cross-reference these IDs with the DataPointConfigSummary entries to get the name, type, and validation rules for each.

​
Using the schema

  • Client-side validation — validate your request body against the schema before sending it to catch missing or misplaced data points early.
  • Code generation — use the schema to auto-generate typed request builders in your integration code.
  • Nesting guidance — the schema is the definitive source for which data points go at which level. The data_point_configs list tells you what exists; the schema tells you where each one belongs.