Decarbonization Plan Tools

Query and manage decarbonization plans — reduction targets, planned actions, baseline emissions, and organizational scope perimeters. Plans define emission reduction strategies against a baseline year, with targets specifying scope-level reduction percentages and actions tracking the concrete initiatives to achieve them.

Some targets and actions include ai_rationale and supporting_sources fields — these are generated by Leia, Dcycle’s AI assistant, when it proposes targets or actions. Manually created items will have these fields as null.

`list_decarb_plans`

List decarbonization plans for the organization, optionally filtered by project. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`project_id`	string	No	—	Filter by linked project UUID

Example response:

{
  "id": "plan-1a2b3c4d-...",
  "project_id": "proj-5e6f7a8b-...",
  "status": "in_progress",
  "base_year": 2023,
  "target_year": 2030,
  "included_scopes": [1, 2, 3],
  "reporting_period_start_month": 1,
  "reporting_period_end_month": 12,
  "strategic_priorities": "Focus on fleet electrification and renewable energy procurement...",
  "budget": 500000,
  "currency_unit_id": "cur-1a2b3c4d-...",
  "config_review_status": "reviewed",
  "created_by": "u-1a2b3c4d-...",
  "report_file_id": null,
  "created_at": "2025-01-10T09:00:00",
  "updated_at": "2025-06-15T11:30:00"
}

Key response fields:

Field	Description
`status`	Plan lifecycle: `draft`, `in_progress`, or `completed`
`base_year` / `target_year`	Baseline and target years for the reduction plan
`included_scopes`	GHG Protocol scopes covered (e.g. `[1, 2, 3]`)
`strategic_priorities`	AI-generated strategic priority summary
`budget`	Total allocated budget for the plan

`get_decarb_plan`

Get baseline emissions data for a decarbonization plan — the actual carbon footprint numbers used as the starting point for reduction calculations. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "base_year": 2023,
  "included_scopes": [1, 2, 3],
  "approach": "operational",
  "site_tco2e": 1245.8,
  "group_tco2e": 3890.2
}

Key response fields:

Field	Description
`site_tco2e`	Primary company (root org) standalone footprint in tCO2e
`group_tco2e`	Consolidated footprint across the entire org perimeter
`approach`	Consolidation approach (always `operational`)

site_tco2e and group_tco2e are null when the plan’s baseline year or included scopes are not yet configured.

`list_decarb_targets`

List reduction targets defined in a decarbonization plan. Each target specifies emission scopes, a reduction percentage, and a target year. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`organization_id`	string	No	default org	Organization UUID

Example response:

[
  {
    "id": "tgt-1a2b3c4d-...",
    "decarbonization_plan_id": "plan-1a2b3c4d-...",
    "organization_id": "a1b2c3d4-...",
    "scope": [1, 2],
    "target_type": "absolute",
    "base_year": 2023,
    "target_year": 2030,
    "base_emissions": 1245.8,
    "reduction_percentage": 42.0,
    "ai_rationale": "Based on SBTi 1.5°C pathway for the transport sector...",
    "supporting_sources": [{"type": "sbti", "reference": "1.5C-transport-2030"}],
    "status": "accepted",
    "created_at": "2025-01-15T10:00:00",
    "updated_at": "2025-02-01T14:30:00"
  }
]

Key response fields:

Field	Description
`scope`	GHG scopes this target covers (e.g. `[1, 2]`)
`target_type`	`absolute` (total reduction) or `intensity` (per-unit reduction)
`base_emissions`	Baseline emissions in tCO2e for the target scopes
`reduction_percentage`	Target reduction (0–100), e.g. `42.0` = 42% reduction
`status`	`proposed` (by Leia), `accepted`, or `rejected`
`ai_rationale`	Leia’s reasoning for the proposed values (null if manual)

`create_decarb_target`

Create a reduction target within a decarbonization plan. Targets define a scope-level emission reduction goal between a base year and a target year. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`base_year`	integer	Yes	—	Baseline year for the target
`target_year`	integer	Yes	—	Year by which the reduction should be achieved
`scope`	list[int]	No	—	GHG scopes covered (values: `1`, `2`, `3`)
`target_type`	string	No	—	`absolute` (total reduction) or `intensity` (per-unit reduction)
`base_emissions`	float	No	—	Baseline emissions in tCO2e for the target scopes
`reduction_percentage`	float	No	—	Target reduction (0–100), e.g. `42.0` = 42% reduction
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Create a 42% reduction target for scopes 1 and 2 by 2030, baseline year 2023"
"Add an intensity-based target to our decarb plan with 30% reduction by 2028"
"Set a new absolute target for scope 3 emissions — 25% reduction from 2024 to 2030"

The plan must already exist — use list_decarb_plans to find the plan_id first. If scope is not set, the API uses the plan’s default included scopes. When base_emissions is omitted, the API calculates it from actual emissions data for the given base year and scopes.

Common errors:

Error	Cause	Fix
`404 Not Found`	Invalid `plan_id`	Verify with `list_decarb_plans`
`422 Unprocessable Entity`	Overlapping target (same scopes/years)	Check existing targets with `list_decarb_targets`

`list_decarb_actions`

List planned decarbonization actions and their progress. Actions are concrete initiatives linked to a specific target. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`organization_id`	string	No	default org	Organization UUID

Example response:

[
  {
    "id": "act-1a2b3c4d-...",
    "decarbonization_plan_id": "plan-1a2b3c4d-...",
    "decarbonization_target_id": "tgt-1a2b3c4d-...",
    "organization_id": "a1b2c3d4-...",
    "title": "Install solar panels at Madrid warehouse",
    "description": "150kW rooftop PV installation covering 60% of facility electricity demand",
    "scope": [2],
    "estimated_co2e_reduction": 85.3,
    "estimated_cost": 120000,
    "payback_period_months": 72,
    "npv": 45000,
    "priority": "medium_term",
    "status": "in_progress",
    "approval_status": "approved",
    "consolidation_type": "technical",
    "initiative_type": "electricity",
    "emission_source": "electricity",
    "saved_quantity": "960 MWh/year",
    "funding_amount": 80000,
    "annual_saving": 18000,
    "launch_date": "2025-06-01",
    "source": "leia",
    "ai_rationale": "Facility has 2000m² available roof space with south exposure...",
    "created_at": "2025-01-20T09:00:00",
    "updated_at": "2025-06-10T16:00:00"
  }
]

Key response fields:

Field	Description
`estimated_co2e_reduction`	Expected tCO2e saved per year
`estimated_cost`	Estimated implementation cost
`priority`	`quick_win`, `medium_term`, or `long_term`
`status`	`proposed`, `accepted`, `in_progress`, `completed`, or `rejected`
`approval_status`	Finance gate: `not_submitted`, `pending`, `approved`, or `rejected`
`consolidation_type`	Reliability of the reduction: `technical` (permanent equipment change), `behavioural` (depends on people or policy continuing, so it can evaporate), or `unknown`. `null` when not classified yet
`initiative_type`	Category: `heating`, `electricity`, `fleet`, `operational`, `suppliers`, or `other`
`source`	Origin: `leia` (AI-proposed), `imported`, or `manual`

`create_decarb_action`

Create a decarbonization action linked to a reduction target. Actions are concrete initiatives (e.g. install solar panels, switch fleet to electric) that contribute to a target’s reduction goal. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`title`	string	Yes	—	Action title (max 255 chars)
`target_id`	string	Yes	—	UUID of the reduction target this action supports
`description`	string	No	—	Detailed description (max 5000 chars)
`scope`	list[int]	No	—	GHG scopes addressed (values: `1`, `2`, `3`)
`estimated_co2e_reduction`	float	No	—	Estimated tCO2e saved per year
`estimated_cost`	float	No	—	Estimated implementation cost
`payback_period_months`	integer	No	—	Months until the investment pays back
`priority`	string	No	—	`quick_win`, `medium_term`, or `long_term`
`initiative_type`	string	No	—	`heating`, `electricity`, `fleet`, `operational`, `suppliers`, or `other`
`launch_date`	string	No	—	Planned start date (`YYYY-MM-DD`)
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Add an action to install 150kW solar panels at the Madrid warehouse, targeting scope 2, estimated 85 tCO2e reduction and €120k cost"
"Create a quick-win action to switch office lighting to LED under our 2030 target"
"Add a fleet electrification action with 72-month payback, launching June 2026"

The target must already exist — use list_decarb_targets to find the target_id. Actions are created with status proposed by default. Use the Dcycle UI to accept, reject, or update status.

Common errors:

Error	Cause	Fix
`404 Not Found`	Invalid `plan_id` or `target_id`	Verify with `list_decarb_plans` / `list_decarb_targets`

`get_decarb_perimeter`

Get the organizational scope/perimeter snapshot for a decarbonization plan — which facilities, emission categories, and scopes are included. Parameters:

Parameter	Type	Required	Default	Description
`plan_id`	string	Yes	—	UUID of the decarbonization plan
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "plan_id": "plan-1a2b3c4d-...",
  "report_file_id": null,
  "snapshot": { ... },
  "generated_at": "2025-06-15T11:30:00",
  "status": "ready",
  "is_stale": false
}

Key response fields:

Field	Description
`snapshot`	Structured artifact snapshot defining the plan perimeter (facilities, scopes, categories)
`status`	Artifact state: `draft`, `needs_input`, `ready`, or `stale`
`is_stale`	Whether the snapshot is outdated compared to current plan data
`report_file_id`	File ID of the generated PDF report (null if not yet generated)

Example prompts:

"List our decarbonization plans"
"What are the baseline emissions for our decarbonization plan?"
"What reduction targets do we have and are they on track?"
"Show all planned actions and their progress"
"Which actions have been approved by finance?"
"What's the estimated CO2 reduction from our solar panel initiative?"
"Which facilities are included in our decarbonization scope?"

Workflow

Discover plans — list_decarb_plans to see available plans and their status
Check baselines — get_decarb_plan to see the actual carbon footprint baseline (site vs group)
Review targets — list_decarb_targets to see scope-level reduction goals and whether they’re accepted
Create targets — create_decarb_target to add new reduction targets with scope, type, and reduction percentage
Track actions — list_decarb_actions to check initiative progress, costs, and approval status
Create actions — create_decarb_action to add concrete initiatives linked to a target
Understand scope — get_decarb_perimeter to see which facilities and emission categories are included

Emissions

GHG emissions data that baselines are calculated from

Projects

Projects that decarbonization plans belong to

Facilities

Facilities included in the decarbonization perimeter

Getting Started

Tools Reference

Reference Data

Decarbonization Plan Tools

Decarbonization Plan Tools

`list_decarb_plans`

`get_decarb_plan`

`list_decarb_targets`

`create_decarb_target`

`list_decarb_actions`

`create_decarb_action`

`get_decarb_perimeter`

Workflow

Emissions

Projects

Facilities

​Decarbonization Plan Tools

​list_decarb_plans

​get_decarb_plan

​list_decarb_targets

​create_decarb_target

​list_decarb_actions

​create_decarb_action

​get_decarb_perimeter

​Workflow

​Related

Emissions

Projects

Facilities

Decarbonization Plan Tools

`list_decarb_plans`

`get_decarb_plan`

`list_decarb_targets`

`create_decarb_target`

`list_decarb_actions`

`create_decarb_action`

`get_decarb_perimeter`

Workflow

Related