Carbon API
The Carbon API provides CRUD operations for emission entries and read access to the emission factor library.
Emission entries
List emission entries
GET /api/v1/emissions
Query parameters
| Parameter | Type | Description |
|---|---|---|
scope |
integer | 1, 2 or 3 |
category |
string | Activity category code |
periodStart |
date | Entries with period_start ≥ this date |
periodEnd |
date | Entries with period_end ≤ this date |
state |
string | draft, submitted, approved, locked |
locationId |
string | Filter by site/location ID |
page |
integer | Page number (default 1) |
pageSize |
integer | Page size (default 50, max 200) |
Response
{
"data": [
{
"id": "em_abc123",
"scope": 1,
"category": "natural_gas",
"subcategory": "natural_gas_uk",
"quantity": 1500.0,
"unit": "kwh",
"tco2e": 0.273,
"periodStart": "2024-01-01",
"periodEnd": "2024-01-31",
"state": "approved",
"location": { "id": "loc_001", "name": "London HQ" },
"factor": {
"code": "NG_UK_2023",
"source": "DEFRA",
"vintage": 2023,
"value": 0.18216,
"unit": "kgCO2e/kWh"
},
"reference": "INV-2024-001",
"createdAt": "2024-02-01T08:30:00Z",
"createdBy": { "id": "usr_001", "email": "user@example.com" }
}
],
"pagination": { "page": 1, "pageSize": 50, "totalItems": 120, "totalPages": 3 }
}
Get an emission entry
GET /api/v1/emissions/{entryId}
Returns the full emission entry object including revision history.
Create an emission entry
POST /api/v1/emissions
Request body
{
"scope": 1,
"category": "natural_gas",
"subcategory": "natural_gas_uk",
"quantity": 1500.0,
"unit": "kwh",
"periodStart": "2024-01-01",
"periodEnd": "2024-01-31",
"locationId": "loc_001",
"reference": "INV-2024-001",
"notes": "January gas meter read",
"factorCode": null
}
| Field | Type | Required | Description |
|---|---|---|---|
scope |
integer | ✅ | 1, 2 or 3 |
category |
string | ✅ | Activity category code |
subcategory |
string | ✅ | Subcategory code |
quantity |
decimal | ✅ | Activity amount |
unit |
string | ✅ | Unit code |
periodStart |
date | ✅ | ISO 8601 date |
periodEnd |
date | ✅ | ISO 8601 date |
locationId |
string | Conditional | Required if multi-site |
reference |
string | Optional | Invoice / meter ref |
notes |
string | Optional | Max 500 chars |
factorCode |
string | Optional | Pin to specific factor; null = auto-select |
Response (201)
The created emission entry object. The tco2e field is computed by the server.
Update an emission entry
PATCH /api/v1/emissions/{entryId}
Only Draft and Submitted entries can be updated. Provide only the fields to change.
Submit an entry for approval
POST /api/v1/emissions/{entryId}/submit
Moves the entry from Draft → Submitted state.
Approve an entry
POST /api/v1/emissions/{entryId}/approve
Requires emissions:write scope and Manager or Admin role.
Reject / return an entry
POST /api/v1/emissions/{entryId}/reject
{ "reason": "quantity appears incorrect — please verify meter reading" }
Delete an entry
DELETE /api/v1/emissions/{entryId}
Only Draft entries can be deleted. Returns 409 Conflict for other states.
Emission factors
Search emission factors
GET /api/v1/emission-factors
Query parameters
| Parameter | Description |
|---|---|
q |
Keyword search |
category |
Filter by category |
source |
DEFRA, EPA, IPCC, custom |
vintage |
Year the factor was published |
unit |
Filter by compatible unit |
Response
{
"data": [
{
"code": "NG_UK_2023",
"name": "Natural gas (UK) — gross calorific value",
"category": "natural_gas",
"source": "DEFRA",
"vintage": 2023,
"value": 0.18216,
"unit": "kgCO2e/kWh",
"ghgComponents": {
"co2": 0.18152,
"ch4": 0.00036,
"n2o": 0.00028
}
}
]
}
Get an emission factor
GET /api/v1/emission-factors/{factorCode}