> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Waste Water Treatment

> Add a measurement period to a waste water facility and calculate its emissions

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.

<Info>
  The facility must be a waste water facility, created with [POST /v1/facilities/waste\_water](/api-reference/facilities/create-waste-water). It can belong to your organization or to a subsidiary you can write to.
</Info>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Body Parameters

<ParamField body="facility_id" type="string" required>
  UUID of the waste water facility the measurement belongs to

  **Example:** `660e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField body="name" type="string">
  Name or reference of the measurement. Returned as `invoice_id` in responses.

  **Example:** `"January 2026"`
</ParamField>

<ParamField body="start_date" type="date" required>
  Start of the measured period (`YYYY-MM-DD`)

  **Example:** `"2026-01-01"`
</ParamField>

<ParamField body="end_date" type="date" required>
  End of the measured period (`YYYY-MM-DD`). Must be on or after `start_date`.

  **Example:** `"2026-01-31"`
</ParamField>

<ParamField body="m3_water_in" type="number" required>
  Influent water volume, in m³

  **Example:** `125000`
</ParamField>

<ParamField body="m3_water_out" type="number" required>
  Effluent (discharged) water volume, in m³

  **Example:** `120000`
</ParamField>

<ParamField body="kg_sludge" type="number" required>
  Sludge produced during the period, in kg

  **Example:** `48000`
</ParamField>

<ParamField body="kg_bod_per_m3_wwt_line" type="number" required>
  BOD concentration of the influent in the waste water treatment line, in kg BOD/m³

  **Example:** `0.3`
</ParamField>

<ParamField body="kg_bod_per_kg_sludge_line" type="number" required>
  BOD content of the sludge in the sludge line, in kg BOD/kg sludge

  **Example:** `0.05`
</ParamField>

<ParamField body="kg_bod_per_m3_wwd_line" type="number" required>
  BOD concentration of the effluent in the waste water discharge line, in kg BOD/m³

  **Example:** `0.02`
</ParamField>

<ParamField body="kg_n_per_m3_wwt_line" type="number" required>
  Nitrogen concentration of the influent in the waste water treatment line, in kg N/m³

  **Example:** `0.04`
</ParamField>

<ParamField body="kg_n_per_m3_wwd_line" type="number" required>
  Nitrogen concentration of the effluent in the waste water discharge line, in kg N/m³

  **Example:** `0.01`
</ParamField>

<ParamField body="kg_r_wwt_line" type="number">
  CH4 recovered in the waste water treatment line, in kg. Defaults to `0`.

  **Example:** `0`
</ParamField>

<ParamField body="kg_r_sludge_line" type="number">
  CH4 recovered in the sludge line, in kg. Defaults to `0`.

  **Example:** `0`
</ParamField>

<ParamField body="file_url" type="string">
  URL of a supporting document for the measurement
</ParamField>

<Note>
  Every numeric field must be `0` or greater.
</Note>

## Response

Returns `201 Created` with the new record, in the same shape as [GET /v1/waste-water-treatments/`{wwt_id}`/detail](/api-reference/waste-water-treatments/detail). The record starts with `status: "uploaded"` and `co2e: null`. Fetch the detail endpoint later to read the calculated emissions.

<ResponseField name="id" type="string">
  Unique identifier (UUID) of the new WWT record
</ResponseField>

<ResponseField name="status" type="string">
  Processing status. `uploaded` on creation, `active` once emissions are calculated, `error` if the calculation failed.
</ResponseField>

<ResponseField name="invoice_id" type="string">
  The `name` you sent, or an empty string if you sent none
</ResponseField>

<ResponseField name="facility_id" type="string">
  UUID of the facility
</ResponseField>

<ResponseField name="quantity" type="number">
  The `m3_water_in` you sent
</ResponseField>

<ResponseField name="base_quantity" type="number">
  The `m3_water_out` you sent
</ResponseField>

<ResponseField name="co2e" type="number | null">
  CO2 equivalent emissions in kg CO2e. `null` until the calculation finishes.
</ResponseField>

See the [detail endpoint](/api-reference/waste-water-treatments/detail#response) for the full list of response fields.

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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']})")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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})`);
    });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Facility 660e8400-e29b-41d4-a716-446655440000 is not a waste water facility",
  "code": "FACILITY_NOT_WASTE_WATER"
}
```

**Solution:** Use a facility created with [POST /v1/facilities/waste\_water](/api-reference/facilities/create-waste-water).

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

**Solution:** Verify your API key is valid and active.

### 404 Not Found

**Cause:** The facility does not exist, or it belongs to an organization you cannot write to

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Facility with id='660e8400-e29b-41d4-a716-446655440000' not found",
  "code": "NOT_FOUND"
}
```

**Solution:** Check the `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, or `end_date` is before `start_date`

**Solution:** Check the request body against the parameters above.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Waste Water Treatment" icon="file" href="/api-reference/waste-water-treatments/detail">
    Read a record and its calculated emissions
  </Card>

  <Card title="List Waste Water Treatments" icon="list" href="/api-reference/waste-water-treatments/list">
    Retrieve all WWT records for a facility
  </Card>

  <Card title="Create Waste Water Facility" icon="building" href="/api-reference/facilities/create-waste-water">
    Create the facility and its treatment lines
  </Card>

  <Card title="Bulk Upload (legacy)" icon="upload" href="/api-reference/legacy/waste-water-treatments/bulk-upload">
    Upload daily measurements with automatic imputation
  </Card>
</CardGroup>