Facility Tools

Facilities are the physical locations where your organization operates — offices, factories, warehouses, data centers, waste water treatment plants, etc. They are the anchor entity for most environmental data: energy invoices, waste records, and water consumption are all linked to a specific facility.

Facilities are the starting point for most queries. Call list_facilities first to discover facility IDs, then use those IDs with list_invoices, list_wastes, or get_greenhouse_gas_emissions.

Read Operations

`list_facilities`

List facilities for an organization with optional filters. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`name`	string	No	—	Filter by name (partial match, case-insensitive)
`country`	string	No	—	ISO 3166-1 alpha-2 country code (e.g. `ES`, `DE`, `FR`)
`type`	string	No	—	Facility type: `office`, `factory`, `warehouse`, `store`, `data_center`, `waste_water_facilities`, `other`
`status`	string	No	—	Status filter: `active`, `archived`
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

Example response:

{
  "items": [
    {
      "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",
      "invoices_in_review_count": 2,
      "categories_without_data": 0
    }
  ],
  "total": 12,
  "page": 1,
  "size": 50,
  "pages": 1
}

Key response fields:

Field	Description
`co2e`	Total CO₂e emissions in kg for this facility
`categories`	Configured consumption categories (e.g. `electricity`, `water`, `heat`)
`cups_list`	CUPS supply point codes (Spanish energy market)
`invoices_in_review_count`	Number of invoices pending review
`categories_without_data`	Categories with no invoices — indicates data gaps

Example prompts:

"List all our active offices in Spain"
"Show me the factories in Germany"
"Which facilities do we have in France?"
"List archived facilities"

`get_facility`

Get a single facility by ID with full details including address, categories, emission totals, and linked data such as waste water treatment configuration. Parameters:

Parameter	Type	Required	Description
`facility_id`	string	Yes	UUID of the facility
`organization_id`	string	No	Organization UUID (uses default if not set)

Returns the same fields as list_facilities items, plus additional fields for waste water treatment facilities:

Field	Description
`water_type`	Water type of the waste water treatment line
`methane_burned`	Whether methane is burned at the facility
`wwt_line`	Waste water treatment line configuration (id + line_code)
`sludge_line`	Sludge treatment line configuration
`wwd_line`	Water discharge line configuration

Example prompts:

"Show me details for facility 550e8400-..."
"What categories are configured for our Madrid office?"

Write Operations

`create_facility`

Create a new facility in the organization. Returns the created facility with its assigned ID.

Address or Country Required: You must provide either an address (from which the country is geocoded automatically) or a country code. If both are provided, the geocoded country from the address takes precedence.

Parameters:

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Facility name (e.g. `"Madrid Office"`, `"Barcelona Warehouse"`)
`type`	string	Yes	—	Facility type: `office`, `factory`, `warehouse`, `store`, `data_center`, `other`
`country`	string	Conditional	—	ISO country code (e.g. `ES`, `FR`). Required if `address` is not provided
`address`	string	Conditional	—	Street address. If provided, country is derived automatically
`logistic_factor`	number	No	0.8	Logistics allocation factor (0 to 1)
`categories`	array[string]	No	—	Consumption categories: `electricity`, `heat`, `water`, `recharge`
`cups_list`	array[string]	No	—	CUPS supply point codes (Spanish energy market)
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid Office",
  "type": "office",
  "country": "ES",
  "address": "Calle Gran Vía 1, Madrid",
  "status": "active",
  "co2e": null,
  "logistic_factor": 0.8,
  "categories": ["heat", "electricity", "water"],
  "created_at": "2024-11-24T10:30:00Z"
}

Example prompts:

"Create a new office in Madrid called 'Madrid HQ'"
"Add a factory in Germany with address Industriestr. 5, Berlin"
"Set up a new warehouse in France tracking electricity and water"

Common errors:

Error	Cause
422: “Either address or country is required.”	Neither `address` nor `country` was provided
422: “Invalid address.”	The address could not be geocoded to a valid country

`update_facility`

Update an existing facility. Only provided fields are changed — omitted fields remain unchanged.

Archiving Side Effects: Setting status to archived will also archive any linked logistic hub and deactivate associated supply contracts.

Parameters:

Parameter	Type	Required	Default	Description
`facility_id`	string	Yes	—	UUID of the facility to update. Use `list_facilities` to find it
`name`	string	No	—	New facility name
`type`	string	No	—	New facility type
`country`	string	No	—	New ISO country code
`address`	string	No	—	New street address
`status`	string	No	—	Set to `active` or `archived`
`logistic_factor`	number	No	—	New logistics factor (0 to 1)
`categories`	array[string]	No	—	New consumption categories
`cups_list`	array[string]	No	—	New CUPS codes
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid HQ (Renamed)",
  "type": "office",
  "country": "ES",
  "status": "active",
  "logistic_factor": 0.9,
  "updated_at": "2024-12-01T14:00:00Z"
}

Example prompts:

"Rename the Madrid office to 'Madrid HQ'"
"Archive the old Barcelona warehouse"
"Update the logistic factor of our Berlin factory to 0.6"
"Add water tracking to the Madrid office categories"

Workflows

Querying facility data

Discover facilities — list_facilities to find by name, country, or type
Inspect a facility — get_facility for full details
Query energy data — list_invoices with the facility_id to see electricity, gas, water consumption
Query waste data — list_wastes with the facility_id for waste records and treatment methods
Query emissions — get_greenhouse_gas_emissions with the facility_id for validated emission totals

Setting up a new facility

Create the facility — create_facility with name, type, and location
Verify it was created — get_facility to confirm details
Upload energy data — Use the API or CLI to upload invoices for the new facility
Check emissions — get_greenhouse_gas_emissions once invoices are processed

Managing existing facilities

Find the facility — list_facilities with name or country filter
Update details — update_facility to rename, change address, or update categories
Archive if needed — update_facility with status: "archived" (cascades to linked resources)

API: Create Facility

REST API endpoint for facility creation

API: Update Facility

REST API endpoint for facility updates

Invoices

Energy invoices linked to a facility

Wastes

Waste records linked to a facility

Emissions

Aggregated emissions by facility

CLI

Manage facilities from the command line

Getting Started

Tools Reference

Reference Data

Facility Tools

Facility Tools

Read Operations

`list_facilities`

`get_facility`

Write Operations

`create_facility`

`update_facility`

Workflows

Querying facility data

Setting up a new facility

Managing existing facilities

API: Create Facility

API: Update Facility

Invoices

Wastes

Emissions

CLI

​Facility Tools

​Read Operations

​list_facilities

​get_facility

​Write Operations

​create_facility

​update_facility

​Workflows

​Querying facility data

​Setting up a new facility

​Managing existing facilities

​Related

API: Create Facility

API: Update Facility

Invoices

Wastes

Emissions

CLI

Facility Tools

Read Operations

`list_facilities`

`get_facility`

Write Operations

`create_facility`

`update_facility`

Workflows

Querying facility data

Setting up a new facility

Managing existing facilities

Related