Skip to main content
Create a material sourcing record with the Cula Tracking API. Base URL: https://api.demo.cula.earth/tracking/v1 All requests require an Authorization: Bearer <access_token> header and a Cula-Organisation-Id header.
1

Get your credentials

OAuth2 client credentials (client_id and client_secret) are issued by the Cula team. Each credential set identifies your consumer and determines which organisations you can access. Contact your Cula representative to obtain credentials.Once you have them, export them for the examples below:
export CULA_CLIENT_ID="your-client-id"
export CULA_CLIENT_SECRET="your-client-secret"
export CULA_ORGANISATION_ID="your-organisation-id"
2

Get an access token

Exchange your credentials for a short-lived access token:
curl -s -X POST https://auth.demo.cula.earth/oauth2/token \
  -u "$CULA_CLIENT_ID:$CULA_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
Extract the access_token from the response and export it:
export CULA_ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIs..."
See authentication for details on token lifecycle and credential rotation.
3

Discover your config

Configs define which data points a resource expects. List your available material sourcing configs:
curl -s https://api.demo.cula.earth/tracking/v1/material-sourcing-configs \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID"
Pick the config relevant to your process and inspect a specific version to see the expected data points:
curl -s https://api.demo.cula.earth/tracking/v1/material-sourcing-configs/stc_01kqzcjrpyf27tgeeekpvvx0zt/versions/scv_01kqzcjrpyf27tgeeekpvvx1ab \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID"
The response includes data_point_configs, which lists each field you can submit: ID, type, unit, and constraints.
4

Create a material sourcing step

Submit a new material sourcing record with your data points:
curl -s -X POST https://api.demo.cula.earth/tracking/v1/material-sourcing \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "GC-HARVEST-2026-001",
    "config_id": "stc_01kqzcjrpyf27tgeeekpvvx0zt",
    "site": { "external_id": "GC-SITE-REFINERY" },
    "executed_at": "2026-05-01T14:30:00-05:00",
    "data_points": [
      {
        "config_id": "dpc_01kqzcjrpyf27tgeq6a84z0yhy",
        "input_value": { "value": 25000, "unit": "kg" }
      }
    ],
    "output": [
      {
        "data_points": [
          {
            "config_id": "dpc_01kqzcjrpyf27tgeq844x9cbr0",
            "input_value": { "value": 24500, "unit": "kg" }
          }
        ]
      }
    ],
    "file_ids": []
  }'
A successful response returns 201 Created with the full resource including a server-generated id.
5

Read back the resource

Retrieve the resource by server ID or by external ID prefixed with ext-:
curl -s https://api.demo.cula.earth/tracking/v1/material-sourcing/ext-GC-HARVEST-2026-001 \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID"
In the response, each data point includes:
  • input_value — the value you submitted.
  • result_value — the server-normalised value (e.g. unit conversion, evaluation output).
The output_containers[].contents[] array shows material contents computed from your output data points.
6

Update a data point

Correct a single data point on an existing resource without resubmitting the entire record:
curl -s -X PUT https://api.demo.cula.earth/tracking/v1/material-sourcing/ms_01jv1abc2def3ghi4jkl5mno6p/data-points/dpc_01kqzcjrpyf27tgeq6a84z0yhy \
  -H "Authorization: Bearer $CULA_ACCESS_TOKEN" \
  -H "Cula-Organisation-Id: $CULA_ORGANISATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input_value": { "value": 24800, "unit": "kg" }
  }'
The response returns the updated resource with the recalculated result_value for the affected data point.

​
Next steps