> ## 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. # Update a material batch ## OpenAPI ````yaml /openapi.json patch /material-batches/{id} openapi: 3.1.0 info: title: Cula Tracking API version: 0.3.10 servers: - url: https://api.demo.cula.earth/tracking/v1 security: [] tags: - name: Organisations description: '' - name: Sites description: '' - name: Machines description: '' - name: Machine Variables description: '' - name: Machine Data Imports description: '' - name: Delivery Configs description: '' - name: Deliveries description: '' - name: Material Sourcing Configs description: '' - name: Material Sourcings description: '' - name: Material Conversion Configs description: '' - name: Material Conversions description: '' - name: Material Utilization Configs description: '' - name: Material Utilizations description: '' - name: Material Batches description: '' - name: Material Pools description: '' - name: Material Containers description: '' - name: Sinks description: '' - name: Documents description: '' - name: Webhooks description: '' paths: /material-batches/{id}: patch: tags: - Material Batches summary: Update a material batch parameters: - name: Cula-Organisation-Id in: header description: >- ID of the organisation the request operates on behalf of (e.g. `org_...`). Must be an organisation the API client has access to. required: true schema: type: string example: org_01k83mfmhgchya944v86ryvhpq - name: id required: true in: path schema: type: string example: mbt_01kjpyrpv5ffa8d2kqmgcqf2r6 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchMaterialBatchRequest' responses: '200': description: The updated material batch. content: application/json: schema: $ref: '#/components/schemas/GetMaterialBatchResponse' '400': description: Invalid request payload or parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: The field limit must not be greater than 100. '401': description: Missing or invalid access token. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Invalid or expired token '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found message: >- Resource with ID xyz_01k56g7aec6dt5zrtamc72vw446 could not be found. '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_server_error message: Internal server error. security: - AccessToken: [] components: schemas: PatchMaterialBatchRequest: type: object properties: display_id: type: string maxLength: 100 description: >- Human-readable identifier, e.g. an EBC batch ID; must be unique per site. Requires the batch to be a draft. example: ba-de-146-1-1 validity_period: description: >- Sets the validity end of an open-ended batch. Requires the batch to be a draft. allOf: - $ref: '#/components/schemas/PatchValidityPeriod' status: type: string enum: - draft - locked description: >- Target lifecycle status: `locked` locks a draft batch (rejected while requirements are still open), `draft` changes a locked batch back to an editable draft. Submitted batches are final and cannot be patched. example: locked data_points: maxItems: 100 description: >- Values for data points of the batch config. Partial: only the listed data points change. Requires the batch to be a draft. type: array items: $ref: '#/components/schemas/DataPointInput' GetMaterialBatchResponse: type: object properties: id: type: string example: mbt_01kjpyrpv5ffa8d2kqmgcqf2r6 description: Unique identifier of the material batch. display_id: type: string description: Human-readable identifier, unique per site. example: ba-de-146-1-1 site: description: The site that owns the batch. allOf: - $ref: '#/components/schemas/SiteReference' status: description: >- 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. example: locked allOf: - $ref: '#/components/schemas/MaterialBatchStatus' config_id: type: string example: mbtc_01kdpna98wj3apgan3j36w499h description: The batch config the batch was created from. config_version_id: type: string example: mbtcv_01kgqrbj1xy7xebdf9easfa0wp description: Config version the batch was created with. created_at: type: string format: date-time example: '2026-05-06T19:34:00Z' description: Time the batch was created. material: description: The one material this batch describes; fixed at creation. allOf: - $ref: '#/components/schemas/MaterialReference' validity_period: oneOf: - $ref: '#/components/schemas/DayValidityPeriod' title: day_based - $ref: '#/components/schemas/TimeValidityPeriod' title: time_based nullable: true description: >- 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. files: description: Files attached to the batch. type: array items: $ref: '#/components/schemas/MaterialBatchFile' data_points: type: array items: oneOf: - $ref: '#/components/schemas/ShortTextDataPoint' title: short_text - $ref: '#/components/schemas/LongTextDataPoint' title: long_text - $ref: '#/components/schemas/MultiTextDataPoint' title: multi_text - $ref: '#/components/schemas/NumberDataPoint' title: number - $ref: '#/components/schemas/PercentageDataPoint' title: percentage - $ref: '#/components/schemas/AmountDataPoint' title: amount - $ref: '#/components/schemas/TimestampDataPoint' title: timestamp - $ref: '#/components/schemas/DurationDataPoint' title: duration - $ref: '#/components/schemas/BooleanDataPoint' title: boolean - $ref: '#/components/schemas/MaterialDataPoint' title: material - $ref: '#/components/schemas/MaterialBatchIdDataPoint' title: material_batch - $ref: '#/components/schemas/ContainerTypeDataPoint' title: container_type - $ref: '#/components/schemas/MaterialPoolDataPoint' title: material_pool discriminator: propertyName: type mapping: short_text: $ref: '#/components/schemas/ShortTextDataPoint' long_text: $ref: '#/components/schemas/LongTextDataPoint' multi_text: $ref: '#/components/schemas/MultiTextDataPoint' number: $ref: '#/components/schemas/NumberDataPoint' percentage: $ref: '#/components/schemas/PercentageDataPoint' amount: $ref: '#/components/schemas/AmountDataPoint' timestamp: $ref: '#/components/schemas/TimestampDataPoint' duration: $ref: '#/components/schemas/DurationDataPoint' boolean: $ref: '#/components/schemas/BooleanDataPoint' material: $ref: '#/components/schemas/MaterialDataPoint' material_batch: $ref: '#/components/schemas/MaterialBatchIdDataPoint' container_type: $ref: '#/components/schemas/ContainerTypeDataPoint' material_pool: $ref: '#/components/schemas/MaterialPoolDataPoint' description: Data points recorded on the batch. required: - id - display_id - site - status - config_id - config_version_id - created_at - material - validity_period - files - data_points Error: type: object properties: code: type: string example: bad_request message: type: string example: The field limit must not be greater than 100. required: - code - message PatchValidityPeriod: type: object properties: end_day: type: string description: >- Exclusive end day as an ISO 8601 calendar date (`2026-06-01`), interpreted in the site's local timezone. Required for day-based batch configs; rejected for time-based ones. example: '2026-06-01' end_time: type: string description: >- Exclusive end instant as an ISO 8601 timestamp with an explicit UTC offset (`2026-06-01T08:00:00Z`), truncated to the minute. Required for time-based batch configs; rejected for day-based ones. example: '2026-06-01T08:00:00Z' description: >- Sets the missing end of an open-ended batch. Only the end can be patched — the start is fixed at creation, and the end is immutable once set. DataPointInput: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config to submit a value for. value: oneOf: - type: string - type: number - type: boolean - type: array items: type: string - type: object required: - value - unit properties: value: type: number unit: type: string description: >- The value to submit. Must match the value format of the data point config's `type` and satisfy the config's `validation` rules and `options` (if any). input_value: oneOf: - type: string - type: number - type: boolean - type: array items: type: string - type: object required: - value - unit properties: value: type: number unit: type: string deprecated: true description: '@deprecated Use `value` instead.' description: A value to submit for a data point. required: - config_id - value SiteReference: type: object properties: id: type: string nullable: true example: ste_01k8g7aec6dt5zrtamc72ww446 external_id: type: string nullable: true example: SITE-EXT-0001 description: >- References a site by its ID and the external ID you assigned to it (if any). required: - id - external_id MaterialBatchStatus: type: string enum: - draft - locked - submitted description: >- 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. MaterialReference: type: object properties: id: type: string example: mat_01kh0fwkq4x8p5ea34dr6e4v2e description: Unique identifier of the material. description: References a material by its ID. required: - id DayValidityPeriod: type: object properties: start_day: type: string description: >- First day of the period as an ISO 8601 calendar date (`2026-05-01`, RFC 3339 `full-date`) in the site's local timezone. example: '2026-05-01' end_day: type: string nullable: true description: >- Exclusive end day, formatted like `start_day`. Null while the batch is still open-ended. Immutable once set. example: '2026-06-01' description: >- The period a batch of a day-based config is valid for — whole calendar days in the site's local timezone, start inclusive, end exclusive; consecutive batches share the boundary value. required: - start_day - end_day TimeValidityPeriod: type: object properties: start_time: type: string description: >- Start of the period as a UTC ISO 8601 timestamp (RFC 3339 `date-time`) truncated to the minute — seconds and milliseconds are always zero. example: '2026-05-01T12:30:00.000Z' end_time: type: string nullable: true description: >- Exclusive end instant, formatted like `start_time`. Null while the batch is still open-ended. Immutable once set. example: '2026-06-01T08:00:00.000Z' description: >- The period a batch of a time-based config is valid for — exact instants truncated to the minute, start inclusive, end exclusive; consecutive batches share the boundary value. required: - start_time - end_time MaterialBatchFile: type: object properties: id: type: string example: fle_01kw9grq4tecva35wdpstzcj5z description: >- ID of the file. Resolve its metadata and contents via the `/files` endpoints. external_id: type: string nullable: true example: MY-CUSTOM-ID description: Optionally assigned external ID of the file. name: type: string example: ebc-certificate.pdf description: The original filename of the uploaded binary. description: Reference to a file attached to the batch. required: - id - external_id - name ShortTextDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - short_text description: The type of the data point. Determines the format of its values. value: type: string nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a single line of text. required: - config_id - config_version_id - name - type - value - input_value - result_value LongTextDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - long_text description: The type of the data point. Determines the format of its values. value: type: string nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding multiple lines of text. required: - config_id - config_version_id - name - type - value - input_value - result_value MultiTextDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - multi_text description: The type of the data point. Determines the format of its values. value: nullable: true description: >- The value of the data point. For derived data points this is the computed result. type: array items: type: string input_value: nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' type: array items: type: string result_value: nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. type: array items: type: string description: Data point holding multiple text items. required: - config_id - config_version_id - name - type - value - input_value - result_value NumberDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - number description: The type of the data point. Determines the format of its values. value: type: number nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: number nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: number nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a number. required: - config_id - config_version_id - name - type - value - input_value - result_value PercentageDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - percentage description: The type of the data point. Determines the format of its values. value: type: number nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: number nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: number nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a percentage (0..1 scale). required: - config_id - config_version_id - name - type - value - input_value - result_value AmountDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - amount description: The type of the data point. Determines the format of its values. value: nullable: true description: >- The value of the data point. For derived data points this is the computed result. type: object allOf: - $ref: '#/components/schemas/AmountValue' input_value: nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' type: object allOf: - $ref: '#/components/schemas/AmountValue' result_value: nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. type: object allOf: - $ref: '#/components/schemas/AmountValue' description: Data point holding an amount, i.e. a combination of a value and a unit. required: - config_id - config_version_id - name - type - value - input_value - result_value TimestampDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - timestamp description: The type of the data point. Determines the format of its values. value: type: string format: date-time nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string format: date-time nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string format: date-time nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a timestamp (ISO 8601 string). required: - config_id - config_version_id - name - type - value - input_value - result_value DurationDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - duration description: The type of the data point. Determines the format of its values. value: type: number nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: number nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: number nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a duration in milliseconds. required: - config_id - config_version_id - name - type - value - input_value - result_value BooleanDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - boolean description: The type of the data point. Determines the format of its values. value: type: boolean nullable: true description: >- The value of the data point. For derived data points this is the computed result. input_value: type: boolean nullable: true deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: boolean nullable: true deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a boolean value. required: - config_id - config_version_id - name - type - value - input_value - result_value MaterialDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - material description: The type of the data point. Determines the format of its values. value: type: string nullable: true example: mat_01kh0fwkq4x8p5ea34dr6e4v2e description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true example: mat_01kh0fwkq4x8p5ea34dr6e4v2e deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true example: mat_01kh0fwkq4x8p5ea34dr6e4v2e deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a material, referenced by its ID. required: - config_id - config_version_id - name - type - value - input_value - result_value MaterialBatchIdDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - material_batch description: The type of the data point. Determines the format of its values. value: type: string nullable: true example: mbt_01kjpyrpv5ffa8d2kqmgcqf2r6 description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true example: mbt_01kjpyrpv5ffa8d2kqmgcqf2r6 deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true example: mbt_01kjpyrpv5ffa8d2kqmgcqf2r6 deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a material batch, referenced by its ID. required: - config_id - config_version_id - name - type - value - input_value - result_value ContainerTypeDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - container_type description: The type of the data point. Determines the format of its values. value: type: string nullable: true example: mct_01k0fs1vdzgjsvm3s7kqm362qr description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true example: mct_01k0fs1vdzgjsvm3s7kqm362qr deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true example: mct_01k0fs1vdzgjsvm3s7kqm362qr deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a container type, referenced by its ID. required: - config_id - config_version_id - name - type - value - input_value - result_value MaterialPoolDataPoint: type: object properties: config_id: type: string example: dptc_01jxdp05c8r7dp4xf89pxcw28q description: The ID of the data point config this value belongs to. config_version_id: type: string example: dptcv_01kfxe6xgmw15gsf204jwj90g5 description: >- The ID of the data point config version the value was recorded against. name: type: string example: Weight gross description: The human-readable name of the data point as it appears in the UI. type: type: string enum: - material_pool description: The type of the data point. Determines the format of its values. value: type: string nullable: true example: mpl_01k2xytkbr0pxazkxbj4j5gr0y description: >- The value of the data point. For derived data points this is the computed result. input_value: type: string nullable: true example: mpl_01k2xytkbr0pxazkxbj4j5gr0y deprecated: true description: '@deprecated Use `value` instead. The value as it was submitted.' result_value: type: string nullable: true example: mpl_01k2xytkbr0pxazkxbj4j5gr0y deprecated: true description: >- @deprecated Use `value` instead. The effective value of the data point, mirroring `value`. description: Data point holding a material pool, referenced by its ID. required: - config_id - config_version_id - name - type - value - input_value - result_value AmountValue: type: object properties: value: type: number example: 50 unit: type: string example: kg description: Unit the amount is expressed in. required: - value - unit securitySchemes: AccessToken: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.demo.cula.earth/oauth2/token scopes: {} description: >- OAuth 2.0 client credentials. Exchange your client_id and client_secret for an access token scoped to the organisation that provides data access. ````