New API: This endpoint is part of the new API architecture with improved design and maintainability.
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 thex-api-key header.
Headers
All requests must include:string
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51fastring
required
Your API key for authenticationExample:
sk_live_1234567890abcdefAvailable Endpoints
List Facilities
Retrieve all facilities with filtering and pagination
Get Facility
Retrieve a single facility by ID
Create Facilities (v2)
Create up to 1,000 facilities in one request
Delete Facilities (v2)
Delete up to 1,000 facilities with their data
Create Facility (v1, deprecated)
Add a new facility to your organization
Update Facility
Modify facility details
Delete Facility (v1, deprecated)
Remove a facility from your organization
Facility Attributes
Core Information
- name (
string, required): Name of the facility (e.g., “Madrid Office”, “Barcelona Warehouse”) - type (
string): Ownership of the site,ownedorrented. Required byPOST /v1/facilities;POST /v2/facilitiestakes notypeand creates every facility asowned. - 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:activeorarchived
Response Format
Facility Object
Error Handling
Common HTTP Status Codes
Use Cases
Find the Facility IDs to Send Consumptions To
Invoices, wastes and the other consumptions name their facility by id (on the v2 routes, thefacility_id of each
facility_percentages entry). Map your own site names to those ids once:
Related Documentation
Authentication Guide
Learn how to get your API key and authenticate requests
Invoices API
Manage energy invoices linked to facilities
MCP Tools
Query facility data from AI assistants via MCP