Create Waste Water Treatment
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
facility_id: '<string>',
name: '<string>',
start_date: '<string>',
end_date: '<string>',
m3_water_in: 123,
m3_water_out: 123,
kg_sludge: 123,
kg_bod_per_m3_wwt_line: 123,
kg_bod_per_kg_sludge_line: 123,
kg_bod_per_m3_wwd_line: 123,
kg_n_per_m3_wwt_line: 123,
kg_n_per_m3_wwd_line: 123,
kg_r_wwt_line: 123,
kg_r_sludge_line: 123,
file_url: '<string>'
})
};
fetch('https://api.dcycle.io/v1/waste-water-treatments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/waste-water-treatments"
payload = {
"facility_id": "<string>",
"name": "<string>",
"start_date": "<string>",
"end_date": "<string>",
"m3_water_in": 123,
"m3_water_out": 123,
"kg_sludge": 123,
"kg_bod_per_m3_wwt_line": 123,
"kg_bod_per_kg_sludge_line": 123,
"kg_bod_per_m3_wwd_line": 123,
"kg_n_per_m3_wwt_line": 123,
"kg_n_per_m3_wwd_line": 123,
"kg_r_wwt_line": 123,
"kg_r_sludge_line": 123,
"file_url": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/waste-water-treatments \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"facility_id": "<string>",
"name": "<string>",
"start_date": "<string>",
"end_date": "<string>",
"m3_water_in": 123,
"m3_water_out": 123,
"kg_sludge": 123,
"kg_bod_per_m3_wwt_line": 123,
"kg_bod_per_kg_sludge_line": 123,
"kg_bod_per_m3_wwd_line": 123,
"kg_n_per_m3_wwt_line": 123,
"kg_n_per_m3_wwd_line": 123,
"kg_r_wwt_line": 123,
"kg_r_sludge_line": 123,
"file_url": "<string>"
}
'{
"id": "<string>",
"status": "<string>",
"invoice_id": "<string>",
"facility_id": "<string>",
"quantity": 123,
"base_quantity": 123,
"co2e": {}
}Create Waste Water Treatment
Add a measurement period to a waste water facility and calculate its emissions
POST
/
v1
/
waste-water-treatments
Create Waste Water Treatment
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
facility_id: '<string>',
name: '<string>',
start_date: '<string>',
end_date: '<string>',
m3_water_in: 123,
m3_water_out: 123,
kg_sludge: 123,
kg_bod_per_m3_wwt_line: 123,
kg_bod_per_kg_sludge_line: 123,
kg_bod_per_m3_wwd_line: 123,
kg_n_per_m3_wwt_line: 123,
kg_n_per_m3_wwd_line: 123,
kg_r_wwt_line: 123,
kg_r_sludge_line: 123,
file_url: '<string>'
})
};
fetch('https://api.dcycle.io/v1/waste-water-treatments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/waste-water-treatments"
payload = {
"facility_id": "<string>",
"name": "<string>",
"start_date": "<string>",
"end_date": "<string>",
"m3_water_in": 123,
"m3_water_out": 123,
"kg_sludge": 123,
"kg_bod_per_m3_wwt_line": 123,
"kg_bod_per_kg_sludge_line": 123,
"kg_bod_per_m3_wwd_line": 123,
"kg_n_per_m3_wwt_line": 123,
"kg_n_per_m3_wwd_line": 123,
"kg_r_wwt_line": 123,
"kg_r_sludge_line": 123,
"file_url": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/waste-water-treatments \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"facility_id": "<string>",
"name": "<string>",
"start_date": "<string>",
"end_date": "<string>",
"m3_water_in": 123,
"m3_water_out": 123,
"kg_sludge": 123,
"kg_bod_per_m3_wwt_line": 123,
"kg_bod_per_kg_sludge_line": 123,
"kg_bod_per_m3_wwd_line": 123,
"kg_n_per_m3_wwt_line": 123,
"kg_n_per_m3_wwd_line": 123,
"kg_r_wwt_line": 123,
"kg_r_sludge_line": 123,
"file_url": "<string>"
}
'{
"id": "<string>",
"status": "<string>",
"invoice_id": "<string>",
"facility_id": "<string>",
"quantity": 123,
"base_quantity": 123,
"co2e": {}
}Create a waste water treatment (WWT) record: the measured inflows, outflows and pollutant loads of one waste water facility over one period (typically a month). Dcycle then calculates the CH4 and N2O emissions of the period asynchronously, using the treatment lines configured on the facility.
See the detail endpoint for the full list of response fields.
Solution: Use a facility created with POST /v1/facilities/waste_water.
Solution: Verify your API key is valid and active.
Solution: Check the
The facility must be a waste water facility, created with POST /v1/facilities/waste_water. It can belong to your organization or to a subsidiary you can write to.
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faBody Parameters
string
required
UUID of the waste water facility the measurement belongs toExample:
660e8400-e29b-41d4-a716-446655440000string
Name or reference of the measurement. Returned as
invoice_id in responses.Example: "January 2026"date
required
Start of the measured period (
YYYY-MM-DD)Example: "2026-01-01"date
required
End of the measured period (
YYYY-MM-DD). Must be on or after start_date.Example: "2026-01-31"number
required
Influent water volume, in m³Example:
125000number
required
Effluent (discharged) water volume, in m³Example:
120000number
required
Sludge produced during the period, in kgExample:
48000number
required
BOD concentration of the influent in the waste water treatment line, in kg BOD/m³Example:
0.3number
required
BOD content of the sludge in the sludge line, in kg BOD/kg sludgeExample:
0.05number
required
BOD concentration of the effluent in the waste water discharge line, in kg BOD/m³Example:
0.02number
required
Nitrogen concentration of the influent in the waste water treatment line, in kg N/m³Example:
0.04number
required
Nitrogen concentration of the effluent in the waste water discharge line, in kg N/m³Example:
0.01number
CH4 recovered in the waste water treatment line, in kg. Defaults to
0.Example: 0number
CH4 recovered in the sludge line, in kg. Defaults to
0.Example: 0string
URL of a supporting document for the measurement
Every numeric field must be
0 or greater.Response
Returns201 Created with the new record, in the same shape as GET /v1/waste-water-treatments/{wwt_id}/detail. The record starts with status: "uploaded" and co2e: null. Fetch the detail endpoint later to read the calculated emissions.
string
Unique identifier (UUID) of the new WWT record
string
Processing status.
uploaded on creation, active once emissions are calculated, error if the calculation failed.string
The
name you sent, or an empty string if you sent nonestring
UUID of the facility
number
The
m3_water_in you sentnumber
The
m3_water_out you sentnumber | null
CO2 equivalent emissions in kg CO2e.
null until the calculation finishes.Example
curl -X POST "https://api.dcycle.io/v1/waste-water-treatments" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"facility_id": "660e8400-e29b-41d4-a716-446655440000",
"name": "January 2026",
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"m3_water_in": 125000,
"m3_water_out": 120000,
"kg_sludge": 48000,
"kg_bod_per_m3_wwt_line": 0.3,
"kg_bod_per_kg_sludge_line": 0.05,
"kg_bod_per_m3_wwd_line": 0.02,
"kg_n_per_m3_wwt_line": 0.04,
"kg_n_per_m3_wwd_line": 0.01
}'
import requests
import os
headers = {
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}
payload = {
"facility_id": "660e8400-e29b-41d4-a716-446655440000",
"name": "January 2026",
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"m3_water_in": 125000,
"m3_water_out": 120000,
"kg_sludge": 48000,
"kg_bod_per_m3_wwt_line": 0.3,
"kg_bod_per_kg_sludge_line": 0.05,
"kg_bod_per_m3_wwd_line": 0.02,
"kg_n_per_m3_wwt_line": 0.04,
"kg_n_per_m3_wwd_line": 0.01,
}
response = requests.post(
"https://api.dcycle.io/v1/waste-water-treatments",
headers=headers,
json=payload,
)
response.raise_for_status()
wwt = response.json()
print(f"Created {wwt['id']} ({wwt['status']})")
const axios = require('axios');
const headers = {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
};
const payload = {
facility_id: '660e8400-e29b-41d4-a716-446655440000',
name: 'January 2026',
start_date: '2026-01-01',
end_date: '2026-01-31',
m3_water_in: 125000,
m3_water_out: 120000,
kg_sludge: 48000,
kg_bod_per_m3_wwt_line: 0.3,
kg_bod_per_kg_sludge_line: 0.05,
kg_bod_per_m3_wwd_line: 0.02,
kg_n_per_m3_wwt_line: 0.04,
kg_n_per_m3_wwd_line: 0.01,
};
axios.post('https://api.dcycle.io/v1/waste-water-treatments', payload, { headers })
.then(response => {
const wwt = response.data;
console.log(`Created ${wwt.id} (${wwt.status})`);
});
Successful Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "waste_water_treatment",
"status": "uploaded",
"invoice_id": "January 2026",
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"facility_id": "660e8400-e29b-41d4-a716-446655440000",
"quantity": 125000.0,
"base_quantity": 120000.0,
"m3_water_out": 120000.0,
"kg_sludge": 48000.0,
"percentage": 1,
"co2e": null,
"co2e_biomass": null,
"unit": {
"id": "987190d0-8ed9-4234-bceb-ab683761a7fe",
"name": "cubic_metre_(m3)_total",
"type": "waste_water_treatments_flow_total"
},
"user": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"first_name": "Ana",
"last_name": "García",
"email": "ana.garcia@company.com",
"prefix": null,
"phone_number": null,
"onboarding_done": true,
"profile_img_url": null
},
"uploaded_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"source_invoice_id": "550e8400-e29b-41d4-a716-446655440000",
"file_url": null,
"linked_projects": [],
"facility_percentages": [],
"custom_values": {},
"custom_refs": null,
"created_at": "2026-02-01T10:30:00Z"
}
Common Errors
400 Bad Request
Cause: The facility exists but is not a waste water facility{
"detail": "Facility 660e8400-e29b-41d4-a716-446655440000 is not a waste water facility",
"code": "FACILITY_NOT_WASTE_WATER"
}
401 Unauthorized
Cause: Missing or invalid API key{
"detail": "Invalid API key",
"code": "INVALID_API_KEY"
}
404 Not Found
Cause: The facility does not exist, or it belongs to an organization you cannot write to{
"detail": "Facility with id='660e8400-e29b-41d4-a716-446655440000' not found",
"code": "NOT_FOUND"
}
facility_id and that it belongs to the organization in x-organization-id or one of its subsidiaries.
422 Validation Error
Cause: A required field is missing, a number is negative, orend_date is before start_date
Solution: Check the request body against the parameters above.
Related Endpoints
Get Waste Water Treatment
Read a record and its calculated emissions
List Waste Water Treatments
Retrieve all WWT records for a facility
Create Waste Water Facility
Create the facility and its treatment lines
Bulk Upload (legacy)
Upload daily measurements with automatic imputation
Was this page helpful?