> ## 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. # Create a material conversion ## OpenAPI ````yaml /openapi.json post /material-conversions 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-conversions: post: tags: - Material Conversions summary: Create a material conversion 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMaterialConversionRequest' responses: '201': description: Material conversion created. content: application/json: schema: $ref: '#/components/schemas/MaterialConversionResponse' '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 '409': description: Conflicting resource state. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: conflict message: >- There exists already an object with external ID MY-CUSTOM-ID within this organisation. '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: CreateMaterialConversionRequest: type: object properties: config_id: type: string example: mcvc_01kyaas94dty6shm2d0j7zw9v8 description: >- The ID of the material conversion config that defines the conversion to create. occurred_at: type: string format: date-time example: '2026-01-15T08:00:00Z' description: >- When the conversion took place: an ISO 8601 date-time with an explicit UTC offset (`Z` or `±hh:mm`). Defaults to now if omitted. external_id: type: string example: MY-CUSTOM-ID description: >- A optional custom ID that can be set to an internal ID from your system. This ID must be unique within all objects of the organisation you operate in. You can later use this external ID to reference and query this object. Be aware that you can update this ID later. If you need an immutable ID, use the object ID returned when creating the object. nullable: false maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9\-_]+$ input_containers: type: array items: oneOf: - $ref: '#/components/schemas/NewContainerInput' title: New Container - $ref: '#/components/schemas/ContainerIdReference' title: Existing Container maxItems: 100 description: >- The containers the conversion consumes. Only applicable to non-unified configs (`unified: false`): describe each container against one of the config's `input_configs` via `config_id`. output_containers: type: array items: oneOf: - $ref: '#/components/schemas/NewContainerInput' title: New Container - $ref: '#/components/schemas/ContainerIdReference' title: Existing Container maxItems: 100 description: >- The containers the conversion produces. Only applicable to non-unified configs (`unified: false`): describe each container against one of the config's `output_configs` via `config_id`. data_points: maxItems: 100 description: >- Values for the conversion's data points. When the config is unified (`unified: true`), the flat array spans the whole flow (conversion step, input and output containers); when `unified` is `false`, only the step's own data points — container values belong to the `input_containers` / `output_containers` items. type: array items: $ref: '#/components/schemas/DataPointInput' required: - config_id MaterialConversionResponse: type: object properties: id: type: string example: mcv_01k1k06s731c8dpsfc8beya4rt description: The ID of the material conversion. config_id: type: string example: mcvc_01kyaas94dty6shm2d0j7zw9v8 description: The ID of the config the conversion was created from. config_version_id: type: string example: mcvcv_01krxsm2pxdgygx26jbyv4ztjy description: The ID of the exact config version the conversion was created from. external_id: type: string nullable: true example: MY-CUSTOM-ID description: Optional external ID of the conversion. display_id: type: string example: PYR-2026-01-15-1 description: Human-readable identifier. site: description: The site the conversion was executed at. allOf: - $ref: '#/components/schemas/SiteRef' occurred_at: type: string format: date-time example: '2026-01-15T08:00:00Z' description: When the conversion took place. created_at: type: string format: date-time example: '2026-01-15T08:00:00Z' description: When the conversion was recorded in Cula. 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 set on the conversion step itself. input_containers: description: >- The material containers the conversion consumed. Always returned, whether the config is unified or not. type: array items: $ref: '#/components/schemas/Container' output_containers: description: >- The material containers the conversion produced. Always returned, whether the config is unified or not. type: array items: $ref: '#/components/schemas/Container' required: - id - config_id - config_version_id - external_id - display_id - site - occurred_at - created_at - data_points - input_containers - output_containers 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 NewContainerInput: type: object properties: config_id: type: string example: mcnc_01k102qfrwthwk6dsggr9y8evn description: The ID of the container config to base the container on. data_points: maxItems: 100 description: >- Values for the container's data points, validated against the container config's data point configs. type: array items: $ref: '#/components/schemas/DataPointInput' description: >- Describes a new container to create, based on one of the container configs the flow's config lists. required: - config_id ContainerIdReference: type: object properties: id: type: string example: mcn_01kqz4g5cjzvwsnnps6q7183q3 description: References an existing container by its ID. required: - id 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 SiteRef: type: object properties: id: type: string example: ste_01k8g7aec6dt5zrtamc72ww446 description: The ID of the site. external_id: type: string nullable: true example: SITE-EXT-0001 description: Optional external ID of the site. description: Reference to a site. required: - id - external_id 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 Container: type: object properties: id: type: string example: mcn_01kqz4g5cjzvwsnnps6q7183q3 config_id: type: string example: mcnc_01k102qfrwthwk6dsggr9y8evn description: The ID of the container config the container is based on. config_version_id: type: string example: mcncv_01kxs8mt2y4711mz04rqs14t0a description: >- The ID of the container config version the container was created against. status: example: available description: >- Whether the container is available as an input to further flows, consumed by one, or deactivated. allOf: - $ref: '#/components/schemas/ContainerStatus' 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: The container's data points. description: >- A material container: a tracked unit of material moving through the system. required: - id - config_id - config_version_id - status - data_points AmountValue: type: object properties: value: type: number example: 50 unit: type: string example: kg description: Unit the amount is expressed in. required: - value - unit ContainerStatus: type: string enum: - available - consumed - deactivated description: >- Whether the container is available as an input to further flows, consumed by one, or deactivated. 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. ````