Skip to main content
POST
← Waste Water Treatments Write one or many measurements of waste water treatment plants (WWTP, EDAR). A measurement is what a plant measured during a period, typically a month: the water in and out, the sludge, and the BOD and nitrogen of each treatment line. Dcycle calculates its CH₄ and N₂O emissions in the background with the lines the plant was created with. The measurements are the ones GET /v1/waste-water-treatments reads. The plant is a facility created with a waste_water block in POST /v2/facilities, which sets its three treatment lines. The request checks every record and writes them all at once, then answers 202 Accepted with an ingest job that calculates them (see how bulk ingestion works). Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

​
How it works

  1. Every record is checked, its plant included: facility_id must be an enabled facility of your perimeter, a waste water treatment plant, with its three treatment lines set. If any record is invalid the whole request is rejected with 422 and nothing is written; rejected is the number of invalid records and errors lists them (up to 100).
  2. The measurements are written at once, with status uploaded. Each belongs to its plant, so to the plant’s organization (the x-organization-id one or a subsidiary of it). Periods of a plant may overlap, as in v1 and the Data Importer: nothing is merged or replaced.
  3. The job calculates them in the background, in chunks, with the IPCC 2019 method and the emission factors of the plant’s lines: No line’s CH₄ goes below 0. The gases are converted to CO₂e with the IPCC GWPs and spread over the days of the period. The treatment and sludge lines are direct emissions of the plant; the discharge is reported apart, under other Scope 3 emissions (WWTP discharges). A measurement keeps the status uploaded with its co2e; one whose calculation fails ends error, without emissions, and its job item is failed with CALCULATION_FAILED.
  4. When every chunk is done the job is completed (or completed_with_errors). For a job submitted with an API key, ingest_job.finished is sent to the webhook endpoints of the x-organization-id organization.

​
Coming from POST /v1/waste-water-treatments

The record is the measurement v1 takes, with these differences:
  • Up to 5,000 measurements per request, all or nothing, with an Idempotency-Key; the answer is a job, not the measurement.
  • A period cannot end in the future.
  • A facility that is not a plant is a record code (FACILITY_NOT_WASTE_WATER), not a 400; a plant without its three lines is rejected too (WASTE_WATER_LINES_NOT_CONFIGURED), where v1 stores the measurement and it ends in error.
  • There is no file_url, nor any other field not listed below.
  • kg_r_wwt_line and kg_r_sludge_line omitted are 0.

​
Request

​
Headers

​
string
required
Your API key (see Authentication).
​
string
required
Your organization. The plants of its perimeter (its own and those of the subsidiaries it may write to) can take measurements. The job and its ingest_job.finished webhook belong to this organization.
​
string
required
1 to 255 characters, one per batch, looked up per organization across every v2 bulk route. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true) instead of writing the measurements again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free, and a request with it is a new one. See The Idempotency-Key.

​
Query Parameters

​
boolean
default:"false"
Check only: the same 422 for invalid records, nothing written, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every record is valid. It does not check or store the Idempotency-Key.

​
Body Parameters

​
array[object]
required
The measurements to write, 1 to 5,000. A field not listed here is rejected (SCHEMA_INVALID). Every number is 0 or more (and under 10¹²).

​
Response

202 Accepted with the job (entity_type: waste_water_treatments, operation: create) and a Location header to it. To read the result:
  • GET /v2/ingest-jobs/{id}/items has one item per record, in the order sent. Its entity_id is the measurement’s id. A failed item carries its error_code.
  • List Waste Water Treatments (?facility_id= the plant) returns the measurements with their status and emissions (co2e, kg CO₂e).
If chunks_done stops moving, see A job that does not finish: never resend the batch with a new Idempotency-Key, because its measurements are already stored.

​
Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED: Request-level errors: 401 for a missing or invalid API key, 403 LOGGED_USER_NOT_MEMBER when the key’s user is not a member of the organization, 422 REQUEST_VALIDATION_FAILED for a malformed body (no records, more than 5,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

​
Limits

Delete Waste Water Treatments (v2)

Delete measurements by id

Create Facilities (v2)

Create the plant with its treatment lines

Get Ingest Job

Follow the calculation

List Waste Water Treatments

The measurements and their emissions