Skip to main content
​

​
v0.3.20

  • A derived data point value, or a value filled from machine data, that breaks the validation rules of its config is stored with error: validation_issue while its object is a draft. POST /material-batches and PATCH /material-batches/{id} answer 201 and 200 for it in place of 400. Treat such a value as missing. A submitted value that breaks a rule is still refused with a 400.
  • The finish and the lock of a material batch refuse such a value with a 400: a create that finishes at once (material sourcings, conversions and utilizations, and deliveries that are not drafts), a PATCH that finishes a delivery, and a PATCH that locks a material batch. The message names each value with its reason, e.g. the computed value(s) of data point(s) <id> (<reason>) violate their validation rules, in place of Computed value(s) for data point config(s) violate their validation rules: <id>.
  • Data point objects carry error: null, one of the machine data outcomes no_machine_data, machine_data_gap and machine_data_fetch_failed (no value), invalid_computation for a computed result that is not a value of the data point’s type (no value), or validation_issue.
  • A 400 for invalid data point values names every invalid value of the same step execution, container, batch, delivery or delivery leg, not only the first. A request that fills several of them at once (a sourcing or conversion with its output containers, a delivery with its legs or payload containers) reports the first one that carries an invalid value.
  • An empty string as the value of a short_text or long_text data point, and an empty list as the value of a multi_text one, clear the data point like null, also where the rules of its config (a URL, options, a minimum number of items) answered 400 for it.
  • A finished create that leaves a mandatory data point unfilled answers in the wording of the finish: mandatory data point(s) <id> must be filled in place of Mandatory data point config(s) are missing a value: <id>. Derived data points and data points the API cannot provide keep their own parts, could not be computed from the submitted values and cannot be provided via the API.
​

​
v0.3.19

  • The 400 response for an invalid data point value now lists every reason the value is invalid, not only the first, and names the bound or unit it breaks, e.g. it must be at most 1000 kg instead of it is higher than the allowed maximum.
​

​
v0.3.19

  • Creating a material utilization from a config with no input_configs now accepts existing containers by id on input_containers, and consumes them. An empty list or config_id items are rejected. This request no longer returns 501 Not Implemented.
​

​
v0.3.18

  • Added POST and DELETE /material-sourcings/{id}/files/{file_id}, /material-conversions/{id}/files/{file_id} and /material-utilizations/{id}/files/{file_id} to attach and detach files of a material sourcing, conversion or utilization.
  • Material sourcing, conversion and utilization get and create responses now expose their attached files.
  • Requests over the limit of your API client are now refused with a 429 response and a Retry-After header. See the new Rate Limits guide.
  • The API Reference documents the 429 response for every endpoint.
​

​
v0.3.17

  • Machines are now machine data sources: one connection machine data is read from. Machines that were read through several connections were split into one machine data source per connection, and the variables read through those connections moved with them. GET /machines lists the new entries too, and machine_id changes for the moved variables.
  • Added GET /machine-data-sources and GET /machine-data-sources/{id}. Machine data sources have mds_ IDs and expose their transport and protocol.
  • Deprecated GET /machines and GET /machines/{id}; they keep returning mch_ IDs. An mch_ ID becomes the mds_ ID of the same source by swapping the prefix.
  • Machine variables now expose machine_data_source_id and accept a machine_data_source_id filter. The machine_id field and filter are deprecated and keep using mch_ IDs.
​

​
v0.3.16

  • A create or finish that is refused because a mandatory machine-fed data point has no machine data at occurred_at now says so, instead of asking for the data point to be filled; the API accepts no value for it.
  • POST /material-batches and PATCH /material-batches/{id} no longer document a 503 response: material batches read no machine data.
​

​
v0.3.15

  • Responses carry the RateLimit-Policy and RateLimit headers with the request limit of your API client. Requests over the limit will get a 429 response with a Retry-After header.
​

​
v0.3.14

  • Deprecated the validation field of TimestampDataPointConfigVersion objects; it is now always null. Values of timestamp data points are no longer checked against min/max or must-be-in-the-past/future rules.
  • Added POST /deliveries/{id}/files/{file_id} and DELETE /deliveries/{id}/files/{file_id} to attach and detach files of a delivery.
  • Deliveries now expose their attached files in the get, create and update responses.
​

​
v0.3.13

  • Added new /machine-data-annotations endpoints to manage machine data annotations.
​

​
v0.3.12

  • Config version objects of Deliveries, Material Sourcings, Material Conversions and Material Utilizations now always specify payload_configs, input_configs and/or output_configs. When creating or updating these objects, one can provide one or more containers per config in payload_containers, input_containers and/or output_containers.
  • The unified field on the corresponding config version objects has been deprecated.
  • Fix: A create that cannot finish a draft delivery returns a 400 error instead of a 500 error.
​

​
v0.3.11

  • Data point values can now be unset: pass value: null in a data_points entry to clear the stored value. Applies wherever data point inputs are accepted (deliveries, delivery payload containers and material batches); values derived from a cleared data point re-compute.
  • Delivery leg sender_site / receiver_site accept an explicit null to unset a side while the delivery is a draft.
​

​
v0.3.10

  • Deliveries now expose their lifecycle status (draft or finished). Draft deliveries may omit mandatory data point values or leg sites.
  • Allow POST /deliveries to create draft deliveries by specifying the status.
  • GET /deliveries keeps returning finished deliveries unless filtered via the new status query parameter to maintain backwards compatibility. Expect this to change in the next breaking release.
  • Added PATCH /deliveries/{id} to allow updating draft deliveries.
  • Added DELETE /deliveries/{id} to delete draft deliveries.
  • Delivery leg sites can now be referenced by their external_id as an alternative to their ID.
  • Fix: occurred_at on delivery creation was interpreted in server timezone and now requires an ISO 8601 date-time with an explicit UTC offset (Z or ±hh:mm)
​

​
v0.3.9

  • Added new /material-utilization-configs endpoints to list and retrieve the configs that material utilizations are created from.
  • Added new /material-utilizations endpoints to create, list and retrieve material utilizations.
​

​
v0.3.8

  • Added new /material-containers endpoints to list and retrieve material containers.
  • Added new /material-sourcing-configs and /material-conversion-configs endpoints to list and retrieve the configs that material sourcings and conversions are created from.
  • Added new /material-sourcings and /material-conversions endpoints to create, list and retrieve material sourcings and conversions.
  • Delivery config versions now expose whether their data points form one unified flow. Delivery creates accept production step values in the flat data_points array and describe their new payload container via payload_containers; responses expose the created containers under the same field. Deprecated the payload, payload_type and payload_config fields.
  • Added the material_pool data point type for data points referencing material pools.
  • Fix: data points filled from machine data no longer accept submitted values and are exposed with accepts_input: false.
  • Fix: Document data_points array size limit of 100 entries.
​

​
v0.3.7

  • Added new /material-batches endpoints to create, list, retrieve, update and delete material batches and to attach and detach their files.
  • Added new /material-batch-configs endpoints to list and retrieve the material batch configs that batches are created from.
  • Added the material_batch data point type for data points referencing material batches.
​

​
v0.3.6

  • Creating a delivery from a configuration whose selected transport emissions configuration contains data points now returns 501 Not Implemented.
​

​
v0.3.5

  • Added new /material-pools endpoints to create, list, retrieve, update and delete material pools.
​

​
v0.3.4

  • Omitting the Cula-Organisation-Id header where it is required now returns 400 instead of 401.
  • Setting the Cula-Organisation-Id header on endpoints that do not accept it (e.g. /webhooks) now returns 400 instead of 401.
​

​
v0.3.3

  • Added new /machines and /machine-variables endpoints to list and retrieve machines and their variables.
  • Added new /machine-data-imports endpoints to ingest time-series values for machine variables and to list and retrieve past imports.
​

​
v0.3.2

  • Added new /files endpoints to create, list, retrieve, and download files, replacing the existing /documents endpoints.
  • Deprecated the /documents endpoints in favor of /files. The old endpoints continue to work for now and will be removed in a future release.
  • Changed the ID prefix of files (formerly “documents”) from doc_ to fle_. This only affects the type prefix, not the ID itself. The deprecated /documents endpoints continue to return doc_-prefixed IDs; the new /files endpoints only return and accept fle_-prefixed IDs. The doc_ prefix will be removed in a future release.
​

​
v0.3.1

  • Added support for authenticating with OAuth 2.0 client credentials.
  • Added Cula-Organisation-Id header that should be specified for all endpoints except /webhooks.
  • Added new endpoints to create organisations and sites.
  • Added new endpoints to query delivery configs.
  • Added new delivery endpoints to query and create deliveries.
  • Corrected the documented type of the sink fields tracked_gross_co2e_removal_in_kg, tracked_net_co2e_removal_in_kg, and verified_net_co2e_removal_in_kg from integer to number.
  • Added nullable verified_at field to sink responses, containing the day the removal was verified by the registry.
  • Added a coordinates and address field on site responses, deprecated the previous location field.
  • Added an organisation field on site responses, deprecated the previous organisation_id field.
​

​
v0.3.0

  • Breaking Return only verified sinks from the /sinks endpoints.
  • Breaking Removed the sink.created event.
  • Breaking Moved from asymmetric to symmetric signatures for webhook deliveries (see Receiving Event Updates): - The webhook secret was renamed from public_key to secret. - The signature format changed from ed25519/v1a to HMAC-SHA256/v1.
  • Breaking Moved the confirmation_document_id field from the material application tracking step to the sink, since the document is sink-specific.
​

​
v0.2.0

  • Breaking Removed tracking step information from the /sinks endpoint (only the /sinks/{id} endpoint includes them).
  • Breaking Replaced the application_matrix field in the material_application tracking step type with an application_description field.
  • Breaking Marked id of registry_reference as nullable.
  • Added rainbow as a possible registry type.
  • Breaking Removed the pyrolysis tracking step type in favor of the more general material_processing step type.
  • Breaking Marked confirmation_document_id of the material_application tracking step type as nullable.
  • Breaking Removed the transport_mode field of the delivery tracking step type.
  • Breaking Marked verified_net_co2e_removal_in_kg as nullable.
  • Breaking Renamed the /document/{id} endpoint to /documents/{id} to conform with the naming scheme.
  • Breaking Removed the legal_address field on the response organisation in favor of a nullable full_address.
  • Breaking Renamed legal_name on the response organisation to name and marked it nullable.
  • Breaking Removed the contact_info field from the response organisation and site.
  • Breaking Marked name of the response site as nullable.
​

​
v0.1.2

  • Removed nullable flags of the response array fields previous_step_ids and document_ids of sinks.
​

​
v0.1.1

  • Marked all response fields as required; optional fields return explicitly null.
  • Breaking Added maxLength constraints to the webhook endpoint fields url and description.
​

​
v0.1.0

  • Initial release.