Update Historical Emission

const options = {
  method: 'PATCH',
  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/{historical_emission_id}', 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/{historical_emission_id}"

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.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/historical-emissions/{historical_emission_id} \
  --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": {}
}

PATCH

historical-emissions

{historical_emission_id}

Update Historical Emission

const options = {
  method: 'PATCH',
  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/{historical_emission_id}', 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/{historical_emission_id}"

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.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/historical-emissions/{historical_emission_id} \
  --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 Update one or more fields of an existing historical emission entry. Only send the fields you want to change — all fields are optional.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

UUID of the historical emission entryExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Body Parameters

All fields are optional — only send what you want to change.

string

Start date (ISO 8601)

string

End date. Must be >= start_date when both are provided.

string

Emission category (see Create for full list)

number

Total CO2e in kilograms (must be > 0)

string

Free text description

string

UUID of evidence file. 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 evidence file

string

Name of evidence file (max 255 chars)

Response

Returns the updated historical emission object with HTTP 200.

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 PATCH "https://api.dcycle.io/v1/historical-emissions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{"total_co2e": 48500.0, "description": "Updated with verified utility data"}'

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",
}

emission_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.patch(
    f"https://api.dcycle.io/v1/historical-emissions/{emission_id}",
    headers=headers,
    json={"total_co2e": 48500.0, "description": "Updated with verified utility data"},
)

entry = response.json()
print(f"Updated: {entry['total_co2e']} kg CO2e")

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',
};

const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

axios.patch(`https://api.dcycle.io/v1/historical-emissions/${id}`, {
  total_co2e: 48500.0,
  description: 'Updated with verified utility data',
}, { headers })
.then(response => console.log(`Updated: ${response.data.total_co2e} kg`));

Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "start_date": "2023-01-01",
  "end_date": "2023-12-31",
  "scope": 2,
  "category": "electricity",
  "total_co2e": 48500.0,
  "description": "Updated with verified utility data",
  "file_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "file_url": "https://storage.dcycle.io/historical/electricity-2023.pdf",
  "file_name": "electricity-2023.pdf",
  "ghg_gas": "co2e",
  "ghg_type": 0,
  "enabled": true,
  "created_at": "2024-02-15T10:00:00Z",
  "updated_at": "2024-03-10T14:22:00Z"
}

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: Historical emission not found, or file_id is not a file your organization can attach

{
  "detail": "Historical emission not found"
}

Get

View the current entry

List

View all entries

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Get

List

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints