> ## 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.

# Wastes API

> Manage waste records and calculate CO2e emissions from waste disposal

# Wastes API

The Wastes API allows you to create, retrieve, update, and delete waste records within your organization's facilities. Each waste record tracks disposal activities and enables automatic CO2e emissions calculations based on waste type, quantity, and disposal method.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## Key Features

* **Waste Tracking**: Create and manage waste disposal records per facility
* **Emission Factors**: Link waste records to standard emission factors (LER/RD codes) or custom emission factors
* **CO2e Calculation**: Automatic emissions calculation based on waste type and quantity
* **Flexible Units**: Support for different quantity units with automatic conversion
* **Pagination Support**: Efficiently retrieve large lists of waste records

## Authentication

All endpoints require authentication using an API key included in the `x-api-key` header.

## Headers

All requests must include:

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

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

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

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

## Available Endpoints

<CardGroup cols={2}>
  <Card title="List Wastes" icon="list" href="/api-reference/wastes/list">
    Retrieve all waste records with filtering and pagination
  </Card>

  <Card title="Create Waste" icon="plus" href="/api-reference/wastes/create">
    Add a new waste record to a facility
  </Card>

  <Card title="Update Waste" icon="pencil" href="/api-reference/wastes/update">
    Modify waste record details
  </Card>
</CardGroup>

## Waste Attributes

### Core Information

* **identification\_name** (`string`, required): Waste identification name or invoice number
* **description** (`string`, optional): Description of the waste
* **start\_date** (`date`, required): Start date of the waste period
* **end\_date** (`date`, required): End date of the waste period
* **base\_quantity** (`float`, required): Waste quantity in the specified unit
* **facility\_id** (`UUID`, required): UUID of the facility this waste belongs to

### Disposal Details

* **destination** (`string`, optional): Waste destination or treatment facility
* **total\_km\_to\_waste\_center** (`float`, optional): Distance to waste center in km

### Emission Configuration

* **waste\_efs\_id** (`UUID`, optional): UUID of the waste emission factor (LER/RD code combination)
* **unit\_id** (`UUID`, optional): UUID of the quantity unit (defaults to kg)
* **custom\_emission\_factor\_id** (`UUID`, optional): UUID of a custom emission factor

### Read-Only Fields

* **co2e** (`float`): Calculated CO2 equivalent emissions in kg CO2e
* **co2e\_biomass** (`float`): Biogenic CO2 emissions in kg CO2e
* **status** (`string`): Current processing status

## Workflow

### Creating a Waste Record

1. **Identify the facility**: Get the facility UUID from the Facilities API
2. **Find the emission factor** (optional): Use waste LER/RD codes to find the appropriate `waste_efs_id`
3. **Create the waste record** with quantity, dates, and emission factor
4. **CO2e is calculated automatically** after creation

## Response Format

### Waste Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "identification_name": "RSU-2024-001",
  "description": "Municipal solid waste",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "base_quantity": 1500.0,
  "quantity": 1500.0,
  "percentage": 1.0,
  "destination": "Waste treatment plant",
  "total_km_to_waste_center": 25.0,
  "status": "active",
  "co2e": 450.75,
  "co2e_biomass": 12.3,
  "enabled": true,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}
```

## Error Handling

### Common HTTP Status Codes

| Status | Meaning          | Solution                                     |
| ------ | ---------------- | -------------------------------------------- |
| 200    | Success          | -                                            |
| 201    | Created          | -                                            |
| 400    | Bad Request      | Check request parameters and format          |
| 401    | Unauthorized     | Verify API key or JWT token                  |
| 403    | Forbidden        | Facility doesn't belong to your organization |
| 404    | Not Found        | Check resource ID                            |
| 422    | Validation Error | Review error details in response             |

## Related Documentation

<CardGroup cols={2}>
  <Card title="Facilities API" icon="building" href="/api-reference/facilities/overview">
    Manage facilities where waste is generated
  </Card>

  <Card title="Scope 3 Category 5" icon="book" href="/guides/emissions/scope-3-category-5-waste">
    Guide for waste-related emissions (GHG Protocol)
  </Card>
</CardGroup>