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

# Facilities API

> Manage facilities and track CO2e emissions for your organization's sites

# Facilities API

The Facilities API allows you to create, retrieve, update, and delete facilities within your organization. Each facility represents a physical site (office, warehouse, factory, etc.) and tracks energy consumption and CO2e emissions.

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

## Key Features

* **Site Management**: Create and manage facilities in your organization
* **Consumption Categories**: Configure which consumption types apply to each facility (heat, electricity, water, recharge)
* **CO2e Tracking**: Automatic emissions calculation based on facility consumption data
* **Regional Support**: ISO country codes for region-specific emission factors
* **CUPS Integration**: Associate electricity supply point codes (CUPS) with facilities
* **Pagination Support**: Efficiently retrieve large lists of facilities

## 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 Facilities" icon="list" href="/api-reference/facilities/list">
    Retrieve all facilities with filtering and pagination
  </Card>

  <Card title="Get Facility" icon="building" href="/api-reference/facilities/get">
    Retrieve a single facility by ID
  </Card>

  <Card title="Create Facility" icon="plus" href="/api-reference/facilities/create">
    Add a new facility to your organization
  </Card>

  <Card title="Update Facility" icon="pencil" href="/api-reference/facilities/update">
    Modify facility details
  </Card>

  <Card title="Delete Facility" icon="trash" href="/api-reference/facilities/delete">
    Remove a facility from your organization
  </Card>
</CardGroup>

## Facility Attributes

### Core Information

* **name** (`string`, required): Name of the facility (e.g., "Madrid Office", "Barcelona Warehouse")
* **type** (`string`, required): Type of facility (e.g., "office", "warehouse", "factory")
* **country** (`string`, required): ISO 3166-1 country code (e.g., "ES", "FR", "DE")
* **address** (`string`, optional): Physical address of the facility

### Configuration

* **categories** (`array[string]`, optional): Consumption categories enabled for this facility (e.g., `["heat", "electricity", "water", "recharge"]`)
* **cups\_list** (`array[string]`, optional): List of CUPS (electricity supply point) codes associated with the facility
* **logistic\_factor** (`float`, optional): Logistic factor for scope 2 calculation in logistics reports (0 to 1, default 0.8)

### Emission Data

* **co2e** (`float`, read-only): Total CO2 equivalent emissions in kg CO2e
* **co2e\_biomass** (`float`, read-only): CO2e from biomass sources
* **status** (`string`): Current status: `active` or `archived`

## Response Format

### Facility Object

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid Office",
  "type": "office",
  "country": "ES",
  "address": "Calle Gran Vía 1, Madrid",
  "status": "active",
  "co2e": 1250.5,
  "co2e_biomass": 0.0,
  "logistic_factor": 0.8,
  "categories": ["heat", "electricity", "water"],
  "cups_list": ["ES0021000000000001AA"],
  "facility_purpose_type": "facilities",
  "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                        | -                                 |
| 204    | No Content (delete successful) | -                                 |
| 401    | Unauthorized                   | Verify API key or JWT token       |
| 404    | Not Found                      | Check resource ID or organization |
| 422    | Validation Error               | Review error details in response  |
| 500    | Server Error                   | Contact support if persists       |

## Use Cases

### Track Office Emissions

Monitor CO2e emissions for all offices in your organization:

```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")
}

response = requests.get(
    "https://api.dcycle.io/v1/facilities",
    headers=headers,
    params={"status[]": ["active"], "type": "office"}
)

total_co2e = sum(f["co2e"] or 0 for f in response.json()["items"])
print(f"Total office emissions: {total_co2e} kg CO2e")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to get your API key and authenticate requests
  </Card>

  <Card title="Invoices API" icon="file-invoice" href="/api-reference/invoices/overview">
    Manage energy invoices linked to facilities
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/facilities">
    Query facility data from AI assistants via MCP
  </Card>
</CardGroup>