Create Historical Emission

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    start_date: '<string>',
    end_date: '<string>',
    category: '<string>',
    total_co2e: 123,
    description: '<string>',
    file_id: '<string>',
    file_url: '<string>',
    file_name: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/historical-emissions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/historical-emissions/"

payload = {
    "start_date": "<string>",
    "end_date": "<string>",
    "category": "<string>",
    "total_co2e": 123,
    "description": "<string>",
    "file_id": "<string>",
    "file_url": "<string>",
    "file_name": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/historical-emissions/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "start_date": "<string>",
  "end_date": "<string>",
  "category": "<string>",
  "total_co2e": 123,
  "description": "<string>",
  "file_id": "<string>",
  "file_url": "<string>",
  "file_name": "<string>"
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "scope": 123,
  "category": "<string>",
  "total_co2e": 123,
  "description": {},
  "ghg_gas": "<string>",
  "ghg_type": 123,
  "enabled": true,
  "file_id": {},
  "file_url": {},
  "file_name": {},
  "created_at": {},
  "updated_at": {}
}

POST

historical-emissions

Create Historical Emission

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    start_date: '<string>',
    end_date: '<string>',
    category: '<string>',
    total_co2e: 123,
    description: '<string>',
    file_id: '<string>',
    file_url: '<string>',
    file_name: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/historical-emissions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/historical-emissions/"

payload = {
    "start_date": "<string>",
    "end_date": "<string>",
    "category": "<string>",
    "total_co2e": 123,
    "description": "<string>",
    "file_id": "<string>",
    "file_url": "<string>",
    "file_name": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/historical-emissions/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "start_date": "<string>",
  "end_date": "<string>",
  "category": "<string>",
  "total_co2e": 123,
  "description": "<string>",
  "file_id": "<string>",
  "file_url": "<string>",
  "file_name": "<string>"
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "scope": 123,
  "category": "<string>",
  "total_co2e": 123,
  "description": {},
  "ghg_gas": "<string>",
  "ghg_type": 123,
  "enabled": true,
  "file_id": {},
  "file_url": {},
  "file_name": {},
  "created_at": {},
  "updated_at": {}
}

← Historical Emissions Create a new manual emission entry. The scope is automatically derived from the category. The entry is included in your organization’s total emissions.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string

required

Start date of the emission period (ISO 8601)Example: "2022-01-01"

string

required

End date of the emission period. Must be greater than or equal to start_date.Example: "2022-12-31"

string

required

Emission category. Determines the GHG scope automatically.Scope 1: process, recharge, stationary, transport, waste_water_treatment_population, waste_water_treatment_sludge, waste_water_treatment_waterScope 2: electricityScope 3: purchases, travels, wastes, capex, employees_in_itinere, employees_in_labore, electricity_generation, electricity_transmission_and_distribution, stationary_generation, transport_generation, transport_distribution_upstream, transport_distribution_downstream, sold_products_waste, upstream_leased, downstream_leased, use_of_product_combustion, use_of_product_electricity, use_of_product_water, waste_water_treatment_discharge, water

number

required

Total CO2e emissions in kilograms. Must be greater than 0.Example: 45200.5

string

Free text description of the emission entryExample: "2022 electricity consumption from utility bills"

string

UUID of an uploaded evidence file to attach. It must be a file of your organization (or of a subsidiary you can write to); any other id returns 404 Not Found.

string

URL of the evidence file

string

Name of the evidence file (max 255 characters)

Response

Returns the created historical emission object with HTTP 201.

string

Historical emission UUID

string

Organization UUID

date

Start date of the emission period (ISO 8601)

date

End date of the emission period (ISO 8601)

integer

GHG scope automatically derived from category (1, 2, or 3)

string

Emission category (e.g. electricity, transport, purchases)

number

Total CO2e emissions in kilograms

string | null

Free text description of the emission entry

string

GHG gas type (e.g. co2e)

integer

GHG type: 0 = fossil, 1 = biomass

boolean

Whether this emission entry is enabled and included in totals

string | null

UUID of the attached evidence file

string | null

URL of the attached evidence file

string | null

Name of the attached evidence file

datetime

Creation timestamp (ISO 8601)

string | null

Last update timestamp (ISO 8601)

Example

curl -X POST "https://api.dcycle.io/v1/historical-emissions/" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2022-01-01",
    "end_date": "2022-12-31",
    "category": "electricity",
    "total_co2e": 45200.5,
    "description": "2022 electricity consumption from utility bills"
  }'

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.dcycle.io/v1/historical-emissions/",
    headers=headers,
    json={
        "start_date": "2022-01-01",
        "end_date": "2022-12-31",
        "category": "electricity",
        "total_co2e": 45200.5,
        "description": "2022 electricity consumption from utility bills",
    },
)

entry = response.json()
print(f"Created: {entry['id']} (scope {entry['scope']})")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json',
};

axios.post('https://api.dcycle.io/v1/historical-emissions/', {
  start_date: '2022-01-01',
  end_date: '2022-12-31',
  category: 'electricity',
  total_co2e: 45200.5,
  description: '2022 electricity consumption from utility bills',
}, { headers })
.then(response => console.log(`Created: ${response.data.id}`));

Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "start_date": "2022-01-01",
  "end_date": "2022-12-31",
  "scope": 2,
  "category": "electricity",
  "total_co2e": 45200.5,
  "description": "2022 electricity consumption from utility bills",
  "ghg_gas": "co2e",
  "ghg_type": 0,
  "enabled": true,
  "file_id": null,
  "file_url": null,
  "file_name": null,
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": null
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: file_id is not a file your organization can attach (it does not exist, is deleted, or belongs to another organization)

{"detail": "File with id='b2c3d4e5-f6a7-8901-bcde-f12345678901' not found", "code": "NOT_FOUND"}

422 Validation Error

Cause: end_date is before start_date

{
  "detail": [
    {
      "loc": ["body", "end_date"],
      "msg": "end_date must be greater than or equal to start_date",
      "type": "value_error"
    }
  ]
}

Cause: total_co2e is not positive

{
  "detail": [
    {
      "loc": ["body", "total_co2e"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

Aggregate figures recorded here are spread into total_impacts, the same table the activity-based calculations write to.

List

View all historical emissions

Update

Modify an existing entry

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

List

Update

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints