Carbon Accounting API

A real Scope 1/2/3 carbon ledger with automation on top: a seeded emission-factor library converts every activity to CO2e at log time, a public REST API lets your systems push data automatically, and the agent writes GHG-Protocol-style reports with hotspots and quantified reductions. Factors are indicative — verify before regulatory filings.

View in marketplace Open dashboard

The Carbon Accounting API agent (agent #20, Operations + Finance) replaces the emissions spreadsheet with a structured, auditable ledger. Activities arrive four ways — the console form, CSV import, the agent parsing a pasted list, or a key-authenticated public REST API your ERP/logistics/finance systems can POST to — and every activity is priced at log time as CO2e = quantity × emission factor, stored with its factor id. The built-in library seeds 42 indicative factors (DEFRA/EPA/IEA-derived, 2024 values) across all three GHG-Protocol scopes, region-aware where it matters, and your custom factors override it. Scheduled runs produce GHG-style reports: scope totals in tCO2e, category breakdown, 12-month trend, top hotspots, and exactly 3 reduction recommendations grounded in your actual top sources. Every number carries the disclaimer: factors are indicative — verify against current DEFRA/EPA/IEA datasets before regulatory or audited filings.

What it does

At its core is a factor-resolved ledger. When an activity is logged — diesel_litre, electricity_kwh, flight_longhaul_km, spend_cloud_it_usd — the factor library resolves the right coefficient with a strict precedence: your org's custom factor for the exact region, then your custom GLOBAL factor, then the seeded factor for the region, then the seeded GLOBAL one (ties broken by most recent valid_year). Units are validated, not coerced: pass 'kWh' against a litre-based factor and the row is rejected with the expected unit, never silently miscomputed. The seeded library covers Scope 1 fuels and vehicles (diesel 2.66 kgCO2e/litre, petrol 2.31, refrigerant R410a leakage at GWP 2088/kg), Scope 2 grid electricity keyed by region (UK 0.207, US 0.369, EU 0.23, world 0.436 kgCO2e/kWh — location-based), and Scope 3 travel (long-haul flights 0.148 kg per passenger-km, economy including radiative forcing), hotels, freight (air 1.13 vs sea 0.016 kg per tonne-km), spend-based EEIO categories (kgCO2e per USD for cloud/IT, professional services, catering, and more), waste, water, and remote work.

Around the ledger sit the agent and the API. The agent answers what-if questions with carbon_estimate (compute-only, nothing persisted), logs activities you describe in plain text after resolving them via carbon_factors_search, and on schedule produces the report: scope 1/2/3 totals to 2dp tCO2e, category shares, the zero-filled 12-month trend with month-on-month change, the top-8 hotspots, and exactly 3 prioritized recommendations generated from the hotspot categories with the tonnage quantified (padded with sensible generics when data is thin) — optionally pushing the top action to the Operations Manager as a task. The public API (/api/v1/carbon/*) is CORS-enabled and key-authenticated: write-only 'ingest' keys (safe to embed in scripts) can POST single activities or batches up to 100 and get computed CO2e back per item; 'full' keys can also read the ledger, footprint aggregates, and the factor library. Requests are metered (carbon_api_ingest per inserted item, carbon_api_read per read) and require an active subscription — the API returns 402 otherwise.

How it works

Your Business

Ingest from four channels

Activities arrive via the console's Activities tab, CSV import (up to 1,000 rows per file), the agent parsing a pasted activity list (resolving each line via carbon_factors_search and rejecting ambiguous ones with a reason), or POST /api/v1/carbon/activities from your systems — single activities or batches up to 100, each item validated individually.

Resolve the emission factor

Each activity_type resolves against the factor library with strict precedence: org custom factor (exact region) → org custom (GLOBAL) → seeded (exact region) → seeded (GLOBAL), ties broken by newest valid_year. Grid electricity and hotel nights are region-keyed (UK / US / EU / GLOBAL); your Reporting region config picks the right one.

Compute and store CO2e

CO2e = quantity × the factor's kgCO2e-per-unit, rounded to 3 decimals and stored on the row with the factor id, scope, category, and source (api / csv / manual / agent) — fully auditable. Unit mismatches are rejected with the expected unit ('expected litre, got kWh'), never silently converted. Unknown activity types are refused until you find a factor or add a custom one.

Aggregate the footprint

carbon_footprint totals any period by GHG-Protocol scope (1 direct / 2 purchased energy, location-based / 3 value chain) and by category; carbon_trend returns the zero-filled monthly series for 12 months; carbon_top_sources ranks the hotspot activity types. The same aggregates power the console Overview and GET /api/v1/carbon/footprint.

Estimate before you commit

carbon_estimate answers what-ifs — 'what's 40 business-class flights LHR–JFK?' — computing against the real factor library without persisting anything, returning the CO2e, the exact factor used, and the disclaimer. Nothing enters the ledger unless you actually log it.

Report with grounded reductions

carbon_make_report saves the GHG-style report: scope totals (2dp tCO2e), category breakdown with shares, the 12-month trend table with month-on-month change, top hotspots, and exactly 3 prioritized recommendations generated from the hotspot categories with expected tonnage cited. Charts (scope pie, monthly line, top-sources bar) render in the console; with push-to-ops autonomy, the top action becomes an Operations Manager task. record_output closes the run.

Outcomes delivered

Setting it up — owner / admin

1
Subscribe and open the Carbon console
Subscribe from the marketplace and deploy from /dashboard/agents/[id]. The console at /dashboard/carbon has five tabs — Overview (charts), Activities, Factors, API, and Reports. No external tools are required; the factor library is built in.
2
Set region, boundary, and context
In config, pick the Reporting region (UK / US / EU / Global — it selects the right grid-electricity and hotel factors), state your Organisational boundary (e.g. 'operational control — HQ + 2 offices', cited in every report), and describe the company (offices, fleet, travel patterns) so parsed logging resolves the right activity types.
3
Seed the ledger
Log a few activities in the Activities tab or import a CSV (header: occurred_on, activity_type, quantity, unit, description; up to 1,000 rows). Browse the Factors tab to see valid activity types — and add custom factors (e.g. your renewable tariff's supplier mix) that override the seeded library.
4
Wire up the API
In the API tab, create a key — choose 'ingest' scope for write-only keys safe to embed in scripts, or 'full' for read access too; the plaintext key (mnki_ingest_… / mnki_live_…) is shown once and stored hashed. Then POST activities from your systems: curl -X POST https://<your-domain>/api/v1/carbon/activities -H 'Authorization: Bearer <key>' -H 'content-type: application/json' -d '{"activity_type":"diesel_litre","quantity":120,"occurred_on":"2026-07-01"}' — the response returns the computed co2e_kg and factor_id. Batches: {"activities":[…]} up to 100 items, each validated individually. Full-scope keys can also GET /activities, /footprint?from=&to=, and /factors.
5
Run the first report, then schedule
Hit Run now — the agent aggregates the footprint, trend, and hotspots and saves the first GHG-style report to the Reports tab. Monthly is the natural schedule; ingestion (API/CSV/console) is continuous regardless.
6
Choose autonomy
Report only, or 'Push the top reduction action to the Operations Manager' — each scheduled report's #1 recommendation then lands as an ops task with the expected saving attached.

Using it day to day — your team

1
Watch the Overview
The console Overview at /dashboard/carbon shows the live footprint charts — monthly trend, scope split, and hotspots — fed by everything logged through the console, CSV, API, and agent.
2
Log as you go
Add activities in the Activities tab, or just tell the agent ('3 flights London–New York in business, 400 litres of diesel for the vans') — it resolves each line against the factor library, logs the valid ones with computed CO2e, and tells you exactly why any line was rejected.
3
Ask emissions questions
Chat uses read-only tools plus estimate: 'what was Q2 Scope 2?', 'what's our biggest source?', 'what would switching that freight to sea save?' — every answer computed from the real ledger and factors, with the disclaimer attached.
4
Check the factor behind any number
Every activity row stores its factor id; the Factors tab shows the coefficient, unit, scope, region, and source for each — so any CO2e figure can be traced to quantity × factor in one click.
5
Read the monthly report
Each scheduled run saves a report to the Reports tab: scope totals in tCO2e, category shares, the trend with month-on-month change, hotspots, and 3 prioritized reductions with quantified expected savings — board-ready.

Use cases

Automate the ledger from your systems

Point your ERP, expense, or logistics system at POST /api/v1/carbon/activities with an ingest key: fuel receipts, kWh readings, flight bookings, and spend lines become CO2e-priced ledger rows automatically, with computed values returned in the response.

The monthly GHG report without consultants

The scheduled run produces a GHG-Protocol-style report — Scope 1/2/3 totals, category breakdown, trend, hotspots, and exactly 3 reduction recommendations grounded in your actual top sources with tonnage quantified.

What-if estimates before committing

carbon_estimate prices decisions against the real factor library without touching the ledger — compare 40 long-haul flights vs rail, or air freight vs sea, before you book.

Spend-based Scope 3 from the P&L

No activity data for a category? Log the spend: EEIO-style factors (kgCO2e per USD) cover cloud/IT, professional services, construction, catering, office supplies, furniture, telecoms, and financial services.

What to expect

A live Scope 1/2/3 footprint dashboard fed continuously by console, CSV, API, and agent-parsed logging
Every activity priced at log time (CO2e = quantity × factor, 3dp) and stored with its factor id — traceable, auditable rows, never invented totals
A 42-factor seeded library (region-aware electricity and hotels, flights with radiative forcing, freight, spend-based EEIO) that your custom factors override
A key-authenticated public REST API (ingest and full scopes, batches up to 100, per-item validation, metered) for system integrations
Scheduled GHG-Protocol-style reports — scope totals, trend, hotspots, and exactly 3 quantified reduction recommendations — always carrying the indicative-factors disclaimer

Metrics to watch

Total tCO2e and the month-on-month change — the headline pair every report leads with
Scope split — Scope 2 is usually the fastest to cut (renewable tariff), Scope 3 usually the biggest
Top sources — the hotspot list the reduction recommendations are generated from; watch the #1 shrink after acting
Coverage — activities logged per month by source (console / csv / api / agent); rising API share means the ledger is automating itself
API usage — carbon_api_ingest and carbon_api_read counts this month against your tier's request limits
Custom-factor share — how much of your footprint is priced on your own verified factors vs the indicative seeded ones (the audit-readiness dial)

FAQ

Where do the emission factors come from — can I trust them for a filing?

The seeded library is 42 indicative factors derived from DEFRA/EPA/IEA-style 2024 datasets, region-aware where it matters. They're solid for management accounting and trend-tracking, but the system itself insists on the caveat: verify factors against current DEFRA/EPA/IEA datasets before regulatory or audited filings. Every report, estimate, and API response carries that disclaimer, and you can override any factor with your own verified custom one.

How does the API work, end to end?

Create a key in the console's API tab (shown once, stored hashed). POST /api/v1/carbon/activities with Authorization: Bearer <key> (or X-API-Key) — a single activity object or {"activities":[…]} up to 100; each item is validated against the factor library and the response returns computed co2e_kg + factor_id per item, with per-item errors for the rest. Ingest-scope keys are write-only and safe to embed; full-scope keys can also GET /activities, /footprint, and /factors. Everything is CORS-enabled, requires an active subscription (402 otherwise), and is metered — ingest per inserted item, reads per request.

Is this audit-ready?

It's audit-friendly by construction: every ledger row stores its quantity, unit, factor id, and computed CO2e, so any total decomposes to quantity × factor — exactly the traceability auditors ask for. What it is not is audit-final: the seeded factors are indicative, so before an audited or regulatory filing (CSRD, SECR), confirm the factors against the current national datasets or load your own as custom factors.

What happens if I log with the wrong unit or an unknown activity type?

The row is rejected, not fudged. Units are validated against the factor ('expected litre, got kWh'), and unknown activity types return an error telling you to search the factor library or add a custom factor. In batches, invalid items are reported individually while valid ones save.

Which scopes and categories are covered?

All three GHG-Protocol scopes: Scope 1 fuels, company vehicles, and refrigerant leakage; Scope 2 grid electricity by region and district heat (location-based); Scope 3 flights (economy, including radiative forcing — the factor notes give business/first multipliers), rail, taxi, hotels, road/air/sea freight, eight spend-based EEIO categories, waste, water, remote-work days, and commuting.

Can it do market-based Scope 2 for our renewable tariff?

Yes — GHG-Protocol dual reporting is built in. Set your supplier-specific electricity factor in the agent's configuration (0 kgCO2e/kWh for a 100% renewable tariff with certificates) and carbon_footprint and every report show Scope 2 both ways: location-based (grid averages) and market-based (purchased electricity re-valued at your supplier factor; other Scope 2 sources keep location values).