Create a material batch

curl --request POST \
  --url https://api.demo.cula.earth/tracking/v1/material-batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Cula-Organisation-Id: <cula-organisation-id>' \
  --data '
{
  "site": {
    "id": "ste_01k8g7aec6dt5zrtamc72ww446"
  },
  "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
  "material": {
    "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e"
  },
  "display_id": "ba-de-146-1-1",
  "data_points": [
    {
      "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
      "value": "<string>",
      "input_value": "<string>"
    }
  ],
  "validity_period": {
    "start_day": "2026-05-01",
    "end_day": "2026-06-01",
    "start_time": "2026-05-01T12:30:00Z",
    "end_time": "2026-06-01T08:00:00Z"
  }
}
'

import requests

url = "https://api.demo.cula.earth/tracking/v1/material-batches"

payload = {
    "site": { "id": "ste_01k8g7aec6dt5zrtamc72ww446" },
    "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
    "material": { "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e" },
    "display_id": "ba-de-146-1-1",
    "data_points": [
        {
            "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
            "value": "<string>",
            "input_value": "<string>"
        }
    ],
    "validity_period": {
        "start_day": "2026-05-01",
        "end_day": "2026-06-01",
        "start_time": "2026-05-01T12:30:00Z",
        "end_time": "2026-06-01T08:00:00Z"
    }
}
headers = {
    "Cula-Organisation-Id": "<cula-organisation-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Cula-Organisation-Id': '<cula-organisation-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    site: {id: 'ste_01k8g7aec6dt5zrtamc72ww446'},
    config_id: 'mbtc_01kdpna98wj3apgan3j36w499h',
    material: {id: 'mat_01kh0fwkq4x8p5ea34dr6e4v2e'},
    display_id: 'ba-de-146-1-1',
    data_points: [
      {
        config_id: 'dptc_01jxdp05c8r7dp4xf89pxcw28q',
        value: '<string>',
        input_value: '<string>'
      }
    ],
    validity_period: {
      start_day: '2026-05-01',
      end_day: '2026-06-01',
      start_time: '2026-05-01T12:30:00Z',
      end_time: '2026-06-01T08:00:00Z'
    }
  })
};

fetch('https://api.demo.cula.earth/tracking/v1/material-batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.demo.cula.earth/tracking/v1/material-batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'site' => [
        'id' => 'ste_01k8g7aec6dt5zrtamc72ww446'
    ],
    'config_id' => 'mbtc_01kdpna98wj3apgan3j36w499h',
    'material' => [
        'id' => 'mat_01kh0fwkq4x8p5ea34dr6e4v2e'
    ],
    'display_id' => 'ba-de-146-1-1',
    'data_points' => [
        [
                'config_id' => 'dptc_01jxdp05c8r7dp4xf89pxcw28q',
                'value' => '<string>',
                'input_value' => '<string>'
        ]
    ],
    'validity_period' => [
        'start_day' => '2026-05-01',
        'end_day' => '2026-06-01',
        'start_time' => '2026-05-01T12:30:00Z',
        'end_time' => '2026-06-01T08:00:00Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Cula-Organisation-Id: <cula-organisation-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.demo.cula.earth/tracking/v1/material-batches"

	payload := strings.NewReader("{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Cula-Organisation-Id", "<cula-organisation-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.demo.cula.earth/tracking/v1/material-batches")
  .header("Cula-Organisation-Id", "<cula-organisation-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.demo.cula.earth/tracking/v1/material-batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Cula-Organisation-Id"] = '<cula-organisation-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "mbt_01kjpyrpv5ffa8d2kqmgcqf2r6",
  "display_id": "ba-de-146-1-1",
  "site": {
    "id": "ste_01k8g7aec6dt5zrtamc72ww446",
    "external_id": "SITE-EXT-0001"
  },
  "status": "locked",
  "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
  "config_version_id": "mbtcv_01kgqrbj1xy7xebdf9easfa0wp",
  "created_at": "2026-05-06T19:34:00Z",
  "material": {
    "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e"
  },
  "validity_period": {
    "start_day": "2026-05-01",
    "end_day": "2026-06-01"
  },
  "files": [
    {
      "id": "fle_01kw9grq4tecva35wdpstzcj5z",
      "external_id": "MY-CUSTOM-ID",
      "name": "ebc-certificate.pdf"
    }
  ],
  "data_points": [
    {
      "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
      "config_version_id": "dptcv_01kfxe6xgmw15gsf204jwj90g5",
      "name": "Weight gross",
      "type": "short_text",
      "value": "<string>",
      "input_value": "<string>",
      "result_value": "<string>"
    }
  ]
}

{
  "code": "bad_request",
  "message": "The field limit must not be greater than 100."
}

{
  "code": "unauthorized",
  "message": "Invalid or expired token"
}

{
  "code": "internal_server_error",
  "message": "Internal server error."
}

POST

material-batches

Create a material batch

curl --request POST \
  --url https://api.demo.cula.earth/tracking/v1/material-batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Cula-Organisation-Id: <cula-organisation-id>' \
  --data '
{
  "site": {
    "id": "ste_01k8g7aec6dt5zrtamc72ww446"
  },
  "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
  "material": {
    "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e"
  },
  "display_id": "ba-de-146-1-1",
  "data_points": [
    {
      "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
      "value": "<string>",
      "input_value": "<string>"
    }
  ],
  "validity_period": {
    "start_day": "2026-05-01",
    "end_day": "2026-06-01",
    "start_time": "2026-05-01T12:30:00Z",
    "end_time": "2026-06-01T08:00:00Z"
  }
}
'

import requests

url = "https://api.demo.cula.earth/tracking/v1/material-batches"

payload = {
    "site": { "id": "ste_01k8g7aec6dt5zrtamc72ww446" },
    "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
    "material": { "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e" },
    "display_id": "ba-de-146-1-1",
    "data_points": [
        {
            "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
            "value": "<string>",
            "input_value": "<string>"
        }
    ],
    "validity_period": {
        "start_day": "2026-05-01",
        "end_day": "2026-06-01",
        "start_time": "2026-05-01T12:30:00Z",
        "end_time": "2026-06-01T08:00:00Z"
    }
}
headers = {
    "Cula-Organisation-Id": "<cula-organisation-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Cula-Organisation-Id': '<cula-organisation-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    site: {id: 'ste_01k8g7aec6dt5zrtamc72ww446'},
    config_id: 'mbtc_01kdpna98wj3apgan3j36w499h',
    material: {id: 'mat_01kh0fwkq4x8p5ea34dr6e4v2e'},
    display_id: 'ba-de-146-1-1',
    data_points: [
      {
        config_id: 'dptc_01jxdp05c8r7dp4xf89pxcw28q',
        value: '<string>',
        input_value: '<string>'
      }
    ],
    validity_period: {
      start_day: '2026-05-01',
      end_day: '2026-06-01',
      start_time: '2026-05-01T12:30:00Z',
      end_time: '2026-06-01T08:00:00Z'
    }
  })
};

fetch('https://api.demo.cula.earth/tracking/v1/material-batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.demo.cula.earth/tracking/v1/material-batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'site' => [
        'id' => 'ste_01k8g7aec6dt5zrtamc72ww446'
    ],
    'config_id' => 'mbtc_01kdpna98wj3apgan3j36w499h',
    'material' => [
        'id' => 'mat_01kh0fwkq4x8p5ea34dr6e4v2e'
    ],
    'display_id' => 'ba-de-146-1-1',
    'data_points' => [
        [
                'config_id' => 'dptc_01jxdp05c8r7dp4xf89pxcw28q',
                'value' => '<string>',
                'input_value' => '<string>'
        ]
    ],
    'validity_period' => [
        'start_day' => '2026-05-01',
        'end_day' => '2026-06-01',
        'start_time' => '2026-05-01T12:30:00Z',
        'end_time' => '2026-06-01T08:00:00Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Cula-Organisation-Id: <cula-organisation-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.demo.cula.earth/tracking/v1/material-batches"

	payload := strings.NewReader("{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Cula-Organisation-Id", "<cula-organisation-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.demo.cula.earth/tracking/v1/material-batches")
  .header("Cula-Organisation-Id", "<cula-organisation-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.demo.cula.earth/tracking/v1/material-batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Cula-Organisation-Id"] = '<cula-organisation-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"site\": {\n    \"id\": \"ste_01k8g7aec6dt5zrtamc72ww446\"\n  },\n  \"config_id\": \"mbtc_01kdpna98wj3apgan3j36w499h\",\n  \"material\": {\n    \"id\": \"mat_01kh0fwkq4x8p5ea34dr6e4v2e\"\n  },\n  \"display_id\": \"ba-de-146-1-1\",\n  \"data_points\": [\n    {\n      \"config_id\": \"dptc_01jxdp05c8r7dp4xf89pxcw28q\",\n      \"value\": \"<string>\",\n      \"input_value\": \"<string>\"\n    }\n  ],\n  \"validity_period\": {\n    \"start_day\": \"2026-05-01\",\n    \"end_day\": \"2026-06-01\",\n    \"start_time\": \"2026-05-01T12:30:00Z\",\n    \"end_time\": \"2026-06-01T08:00:00Z\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "mbt_01kjpyrpv5ffa8d2kqmgcqf2r6",
  "display_id": "ba-de-146-1-1",
  "site": {
    "id": "ste_01k8g7aec6dt5zrtamc72ww446",
    "external_id": "SITE-EXT-0001"
  },
  "status": "locked",
  "config_id": "mbtc_01kdpna98wj3apgan3j36w499h",
  "config_version_id": "mbtcv_01kgqrbj1xy7xebdf9easfa0wp",
  "created_at": "2026-05-06T19:34:00Z",
  "material": {
    "id": "mat_01kh0fwkq4x8p5ea34dr6e4v2e"
  },
  "validity_period": {
    "start_day": "2026-05-01",
    "end_day": "2026-06-01"
  },
  "files": [
    {
      "id": "fle_01kw9grq4tecva35wdpstzcj5z",
      "external_id": "MY-CUSTOM-ID",
      "name": "ebc-certificate.pdf"
    }
  ],
  "data_points": [
    {
      "config_id": "dptc_01jxdp05c8r7dp4xf89pxcw28q",
      "config_version_id": "dptcv_01kfxe6xgmw15gsf204jwj90g5",
      "name": "Weight gross",
      "type": "short_text",
      "value": "<string>",
      "input_value": "<string>",
      "result_value": "<string>"
    }
  ]
}

{
  "code": "bad_request",
  "message": "The field limit must not be greater than 100."
}

{
  "code": "unauthorized",
  "message": "Invalid or expired token"
}

{
  "code": "internal_server_error",
  "message": "Internal server error."
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access.

Headers

Cula-Organisation-Id

string

required

ID of the organisation the request operates on behalf of (e.g. org_...). Must be an organisation the API client has access to.

Example:

"org_01k83mfmhgchya944v86ryvhpq"

Body

application/json

site

object

required

The site that owns the batch; must be the site of config_id. Reference it either by its ID or by its external ID, but not both.

Option 1
Option 2

Show child attributes

config_id

string

required

The batch config to create the batch from; its active version applies.

Example:

"mbtc_01kdpna98wj3apgan3j36w499h"

material

object

required

The one material this batch describes; must be selectable for the config and cannot be changed later.

Show child attributes

display_id

string

Human-readable identifier. Must be unique per site. Omit to assign it later via PATCH /material-batches/{id} — it is required for locking the batch.

Maximum string length: 100

Example:

"ba-de-146-1-1"

data_points

object[]

Values for data points of the batch config. Batches are created as drafts, so values are optional at creation.

Maximum array length: 100

Show child attributes

validity_period

object

Required for day-based and time-based configs; must be omitted when the config does not track validity periods.

Show child attributes

Response

The created material batch.

string

required

Unique identifier of the material batch.

Example:

"mbt_01kjpyrpv5ffa8d2kqmgcqf2r6"

display_id

string

required

Human-readable identifier, unique per site.

Example:

"ba-de-146-1-1"

site

object

required

The site that owns the batch.

Show child attributes

status

enum<string>

required

Lifecycle status. draft batches are still editable, locked batches are read-only but can be changed back to draft, submitted batches have at least one submitted sink and are final.

Available options:

draft,

locked,

submitted

Example:

"locked"

config_id

string

required

The batch config the batch was created from.

Example:

"mbtc_01kdpna98wj3apgan3j36w499h"

config_version_id

string

required

Config version the batch was created with.

Example:

"mbtcv_01kgqrbj1xy7xebdf9easfa0wp"

created_at

string<date-time>

required

Time the batch was created.

Example:

"2026-05-06T19:34:00Z"

material

object

required

The one material this batch describes; fixed at creation.

Show child attributes

validity_period

day_based · object

required

The variant follows the batch config: day-based configs return start_day/end_day, time-based configs start_time/end_time. Null if the config does not require a validity period.

day_based
time_based

Show child attributes

files

object[]

required

Files attached to the batch.

Show child attributes

data_points

required

Data points recorded on the batch.

Data point holding a single line of text.

Show child attributes

General

Material Tracking

Machine Data

Create a material batch

Authorizations

Headers

Body

Response