Quickstart

This page makes two calls: it lists the companies your key can access, then reads one company’s emissions. You need an API key with the company:read and emissions:read scopes (see Get access).

The samples use curl, Python with requests (pip install requests), and Node.js 18 or later, whose built-in fetch needs no packages. The Node.js samples are ES modules: save them as .mjs.

Set your key

Keep the key out of your code: put it in an environment variable, which every sample below reads.


export ENERGI_API_KEY="<your API key>"

List your companies

GET /v3/company returns every company the key can access. The id of each is what you put in /v3/company/{companyId}/… for every other operation.

curl


curl --max-time 60 "https://api.energi.ai/v3/company" \
  -H "Authorization: Bearer $ENERGI_API_KEY"

Python


import os
 
import requests
 
BASE_URL = "https://api.energi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ENERGI_API_KEY']}"}
 
response = requests.get(f"{BASE_URL}/v3/company", headers=HEADERS, timeout=60)
response.raise_for_status()
 
for company in response.json()["data"]:
    print(company["id"], company["name"], company["orgNumber"])

Node.js


const BASE_URL = 'https://api.energi.ai'
const HEADERS = { Authorization: `Bearer ${process.env.ENERGI_API_KEY}` }
 
const response = await fetch(`${BASE_URL}/v3/company`, {
  headers: HEADERS,
  signal: AbortSignal.timeout(60_000)
})
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`)
}
 
const { data } = await response.json()
for (const company of data) {
  console.log(company.id, company.name, company.orgNumber)
}

curl


curl --max-time 60 "https://api.us.energi.ai/v3/company" \
  -H "Authorization: Bearer $ENERGI_API_KEY"

Python


import os
 
import requests
 
BASE_URL = "https://api.us.energi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ENERGI_API_KEY']}"}
 
response = requests.get(f"{BASE_URL}/v3/company", headers=HEADERS, timeout=60)
response.raise_for_status()
 
for company in response.json()["data"]:
    print(company["id"], company["name"], company["orgNumber"])

Node.js


const BASE_URL = 'https://api.us.energi.ai'
const HEADERS = { Authorization: `Bearer ${process.env.ENERGI_API_KEY}` }
 
const response = await fetch(`${BASE_URL}/v3/company`, {
  headers: HEADERS,
  signal: AbortSignal.timeout(60_000)
})
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`)
}
 
const { data } = await response.json()
for (const company of data) {
  console.log(company.id, company.name, company.orgNumber)
}

The response:


{
  "data": [
    { "id": "1042", "name": "Energi.AI AS", "orgNumber": "927611074" }
  ],
  "meta": { "nextCursor": null }
}

Every response is an object with data and, where there is something to say about it, meta. Here meta.nextCursor is null, which means you have the whole list (see Lists). Ids are strings: use them as they are.

Read a company’s emissions

GET /v3/company/{companyId}/emissions/summary returns a company’s emissions over a range of months. All four query parameters are required: the range (from, to), the size of each period (granularity) and the unit (emissionsUnit).

curl


curl --max-time 60 -G "https://api.energi.ai/v3/company/1042/emissions/summary" \
  -H "Authorization: Bearer $ENERGI_API_KEY" \
  -d from=2025-01 -d to=2025-12 -d granularity=QUARTER -d emissionsUnit=t

Python


import os
 
import requests
 
BASE_URL = "https://api.energi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ENERGI_API_KEY']}"}
company_id = "1042"
 
response = requests.get(
    f"{BASE_URL}/v3/company/{company_id}/emissions/summary",
    headers=HEADERS,
    params={"from": "2025-01", "to": "2025-12", "granularity": "QUARTER", "emissionsUnit": "t"},
    timeout=60,
)
response.raise_for_status()
summary = response.json()
 
print(summary["data"]["emissions"], summary["data"]["emissionsUnit"])
for period in summary["data"]["periods"]:
    print(period["period"], period["emissions"])

Node.js


const BASE_URL = 'https://api.energi.ai'
const HEADERS = { Authorization: `Bearer ${process.env.ENERGI_API_KEY}` }
const companyId = '1042'
 
const query = new URLSearchParams({
  from: '2025-01',
  to: '2025-12',
  granularity: 'QUARTER',
  emissionsUnit: 't'
})
const response = await fetch(
  `${BASE_URL}/v3/company/${companyId}/emissions/summary?${query}`,
  { headers: HEADERS, signal: AbortSignal.timeout(60_000) }
)
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`)
}
 
const { data } = await response.json()
console.log(data.emissions, data.emissionsUnit)
for (const period of data.periods) {
  console.log(period.period, period.emissions)
}

curl


curl --max-time 60 -G "https://api.us.energi.ai/v3/company/1042/emissions/summary" \
  -H "Authorization: Bearer $ENERGI_API_KEY" \
  -d from=2025-01 -d to=2025-12 -d granularity=QUARTER -d emissionsUnit=t

Python


import os
 
import requests
 
BASE_URL = "https://api.us.energi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ENERGI_API_KEY']}"}
company_id = "1042"
 
response = requests.get(
    f"{BASE_URL}/v3/company/{company_id}/emissions/summary",
    headers=HEADERS,
    params={"from": "2025-01", "to": "2025-12", "granularity": "QUARTER", "emissionsUnit": "t"},
    timeout=60,
)
response.raise_for_status()
summary = response.json()
 
print(summary["data"]["emissions"], summary["data"]["emissionsUnit"])
for period in summary["data"]["periods"]:
    print(period["period"], period["emissions"])

Node.js


const BASE_URL = 'https://api.us.energi.ai'
const HEADERS = { Authorization: `Bearer ${process.env.ENERGI_API_KEY}` }
const companyId = '1042'
 
const query = new URLSearchParams({
  from: '2025-01',
  to: '2025-12',
  granularity: 'QUARTER',
  emissionsUnit: 't'
})
const response = await fetch(
  `${BASE_URL}/v3/company/${companyId}/emissions/summary?${query}`,
  { headers: HEADERS, signal: AbortSignal.timeout(60_000) }
)
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`)
}
 
const { data } = await response.json()
console.log(data.emissions, data.emissionsUnit)
for (const period of data.periods) {
  console.log(period.period, period.emissions)
}

The response, shortened to one period, one scope and one category:


{
  "data": {
    "companyId": "1042",
    "emissionsUnit": "tCO2e",
    "granularity": "QUARTER",
    "from": "2025-01",
    "to": "2025-12",
    "emissions": 4821.55,
    "periods": [
      {
        "period": "2025-Q1",
        "periodStart": "2025-01-01",
        "periodEnd": "2025-03-31",
        "emissions": 1284.51,
        "scopes": [
          {
            "scope": "SCOPE_1",
            "emissions": 210.4,
            "categories": [
              {
                "code": "STATIONARY_COMBUSTION",
                "label": "Stationary combustion",
                "emissions": 180.2
              }
            ]
          }
        ]
      }
    ]
  },
  "meta": { "status": "UP_TO_DATE", "asOf": "2026-09-16T09:12:04.000Z" }
}

data says how to read its own numbers: the unit, the range and the period size are in it, next to the figures. meta says how current they are. Read emissions explains every field.

Next steps

Authentication: what the API checks on every request, and what 401 and 403 mean.
Errors and limits: the error format, retries and the rate limit.
Upload data: send your own activity and finance records.