REST API v1

Emisso Developer API

Pull your carbon emissions data into external dashboards, ERPs, and reporting tools. Read-only access to your organization, facilities, emissions, and reports.

Bearer Token Auth

Simple API key authentication for scripts and integrations

6 Endpoints

Organization, facilities, emissions, summary, and reports

Pro Plan

Available on the Pro plan ($199/mo)

Base URL

https://app.emisso.app/api/v1

All endpoints are relative to this base URL. Responses are JSON with a consistent envelope: { data, meta } for success, { error: { code, message } } for errors.

Pro plan required. API access is available on the Pro plan ($199/mo). View pricing or start your free trial.

Authentication

All API requests require a Bearer token in the Authorization header. API keys can be created and managed from Settings → API.

Example Request

curl https://app.emisso.app/api/v1/organization \
  -H "Authorization: Bearer emso_live_abc123..."

Key Format

API keys use the prefix emso_live_ followed by 43 characters of base64url-encoded randomness (256 bits of entropy).

Keys are hashed with SHA-256 before storage — we never store your key in plain text. The full key is shown exactly once at creation time. If you lose it, revoke it and create a new one.

Maximum 5 active keys per organization.

Keep your keys secret. Do not commit API keys to version control or expose them in client-side code. Use environment variables in your backend applications.

Rate Limits

The API enforces a sliding window rate limit of 60 requests per minute per organization. This limit is shared across all API keys belonging to the same organization.

Limit	Value
Requests per minute	60
Window type	Sliding window (1 minute)
Scope	Per organization (shared across all keys)

When you exceed the rate limit, the API returns a 429 status code with the rate_limited error code. Wait a moment and retry.

Errors

All errors return a JSON object with a consistent structure:

Error Response

{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or unknown API key"
  }
}

Code	HTTP Status	Description
`missing_auth`	401	No Authorization header provided
`invalid_auth`	401	Authorization header is not using Bearer scheme
`invalid_key`	401	API key is not recognized
`key_revoked`	401	API key has been revoked
`key_expired`	401	API key has expired
`plan_required`	403	Organization is not on the Pro plan
`subscription_inactive`	403	Subscription is not active
`rate_limited`	429	Too many requests — slow down
`validation_error`	400	Invalid query parameter value
`not_found`	404	Requested resource does not exist
`internal_error`	500	Unexpected server error

Pagination

List endpoints support offset-based pagination using limit and offset query parameters.

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of results to return. Default varies by endpoint. Maximum 100.
`offset`	integer	Optional	Number of results to skip. Default 0.

Paginated Response

{
  "data": [ ... ],
  "meta": {
    "total": 142,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Endpoints

Get Organization

GET/api/v1/organization

Returns the organization profile associated with the API key.

Example Request

curl https://app.emisso.app/api/v1/organization \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": {
    "name": "Acme Corp",
    "country": "AU",
    "industry": "manufacturing",
    "reporting_year": 2025,
    "reporting_period_type": "calendar_year"
  },
  "meta": {}
}

List Facilities

GET/api/v1/facilities

Returns a paginated list of facilities belonging to the organization.

Query Parameters

Parameter	Type	Required	Description
`active`	boolean	Optional	Filter by active status. "true" or "false".
`limit`	integer	Optional	Results per page. Default 50, max 100.
`offset`	integer	Optional	Number of results to skip. Default 0.

Example Request

curl "https://app.emisso.app/api/v1/facilities?active=true&limit=10" \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Melbourne HQ",
      "address": "123 Collins St, Melbourne VIC 3000",
      "country": "AU",
      "region": "VIC",
      "floor_area_m2": 500,
      "building_share_pct": 100,
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

List Emissions

GET/api/v1/emissions

Returns a paginated list of activity entries (emissions data) with calculated CO2e values.

Query Parameters

Parameter	Type	Required	Description
`scope`	integer	Optional	Filter by scope: 1, 2, or 3.
`year`	integer	Optional	Filter by reporting year (e.g. 2025).
`facility_id`	uuid	Optional	Filter by facility ID.
`category`	string	Optional	Filter by emission category (e.g. "stationary_combustion").
`limit`	integer	Optional	Results per page. Default 50, max 100.
`offset`	integer	Optional	Number of results to skip. Default 0.

Example Request

curl "https://app.emisso.app/api/v1/emissions?scope=1&year=2025&limit=5" \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "facility_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "reporting_year": 2025,
      "scope": 1,
      "category": "stationary_combustion",
      "subcategory": "natural_gas",
      "activity_type": "Natural Gas",
      "quantity": 12500,
      "unit": "kWh",
      "description": "Office heating - natural gas",
      "data_quality": "measured",
      "emissions_kg_co2e": 2287.5,
      "market_based_kg_co2e": null,
      "electricity_source": null,
      "calculation_method": "activity_based",
      "period_start": "2025-01-01",
      "period_end": "2025-12-31",
      "created_at": "2025-03-10T14:22:00Z",
      "updated_at": "2025-03-10T14:22:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "limit": 5,
    "offset": 0,
    "has_more": true
  }
}

Emissions Summary

GET/api/v1/emissions/summary

Returns aggregated emission totals by scope and category breakdown. Ideal for dashboards and high-level reporting.

Query Parameters

Parameter	Type	Required	Description
`year`	integer	Optional	Reporting year. Defaults to the organization's current reporting year.

Example Request

curl "https://app.emisso.app/api/v1/emissions/summary?year=2025" \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": {
    "reporting_year": 2025,
    "total_emissions_kg_co2e": 84523.67,
    "scope_1_kg_co2e": 12450.30,
    "scope_2_kg_co2e": 28930.12,
    "scope_3_kg_co2e": 43143.25,
    "entry_count": 47,
    "categories": [
      {
        "category": "stationary_combustion",
        "scope": 1,
        "total_kg_co2e": 8230.50,
        "entry_count": 6
      },
      {
        "category": "mobile_combustion",
        "scope": 1,
        "total_kg_co2e": 4219.80,
        "entry_count": 3
      },
      {
        "category": "purchased_electricity",
        "scope": 2,
        "total_kg_co2e": 28930.12,
        "entry_count": 12
      },
      {
        "category": "business_travel",
        "scope": 3,
        "total_kg_co2e": 15200.00,
        "entry_count": 8
      },
      {
        "category": "purchased_goods_services",
        "scope": 3,
        "total_kg_co2e": 27943.25,
        "entry_count": 18
      }
    ]
  },
  "meta": {}
}

List Reports

GET/api/v1/reports

Returns a paginated list of reports with metadata. Does not include the full report_data payload (use the detail endpoint for that).

Query Parameters

Parameter	Type	Required	Description
`year`	integer	Optional	Filter by reporting year.
`status`	string	Optional	Filter by report status (e.g. "draft", "final").
`limit`	integer	Optional	Results per page. Default 20, max 100.
`offset`	integer	Optional	Number of results to skip. Default 0.

Example Request

curl "https://app.emisso.app/api/v1/reports?status=final&year=2025" \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "reporting_year": 2025,
      "report_type": "annual",
      "framework": "ghg_protocol",
      "status": "final",
      "total_scope1_kg": 12450.30,
      "total_scope2_kg": 28930.12,
      "total_scope3_kg": 43143.25,
      "total_emissions_kg": 84523.67,
      "shared_url": "https://app.emisso.app/shared/report/abc123",
      "created_at": "2025-06-15T09:00:00Z",
      "updated_at": "2025-06-20T14:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Report Detail

GET/api/v1/reports/:id

Returns a single report including the full report_data JSONB payload. Use this to retrieve the complete report contents for external rendering or archival.

Path Parameters

Parameter	Type	Required	Description
`id`	uuid	Required	The report ID.

Example Request

curl https://app.emisso.app/api/v1/reports/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "Authorization: Bearer emso_live_abc123..."

Response

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "reporting_year": 2025,
    "report_type": "annual",
    "framework": "ghg_protocol",
    "status": "final",
    "report_data": {
      "organization": { ... },
      "methodology": { ... },
      "scope1": { ... },
      "scope2": { ... },
      "scope3": { ... },
      "summary": { ... }
    },
    "total_scope1_kg": 12450.30,
    "total_scope2_kg": 28930.12,
    "total_scope3_kg": 43143.25,
    "total_emissions_kg": 84523.67,
    "shared_url": "https://app.emisso.app/shared/report/abc123",
    "created_at": "2025-06-15T09:00:00Z",
    "updated_at": "2025-06-20T14:30:00Z"
  },
  "meta": {}
}

Ready to integrate?

Create your API key in Settings and start pulling emissions data into your tools in minutes. API access is available on the Pro plan.

Limit

Value

Requests per minute

Window type

Sliding window (1 minute)

Scope

Per organization (shared across all keys)

Code

HTTP Status

Description

missing_auth

401

No Authorization header provided

invalid_auth

401

Authorization header is not using Bearer scheme

invalid_key

401

API key is not recognized

key_revoked

401

API key has been revoked

key_expired

401

API key has expired

plan_required

403

Organization is not on the Pro plan

subscription_inactive

403

Subscription is not active

rate_limited

429

Too many requests — slow down

validation_error

400

Invalid query parameter value

not_found

404

Requested resource does not exist

internal_error

500

Unexpected server error

Parameter

Type

Required

Description

limit

integer

Optional

Number of results to return. Default varies by endpoint. Maximum 100.

offset

integer

Optional

Number of results to skip. Default 0.

Parameter

Type

Required

Description

active

boolean

Optional

Filter by active status. "true" or "false".

limit

integer

Optional

Results per page. Default 50, max 100.

offset

integer

Optional

Number of results to skip. Default 0.

{ "data": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Melbourne HQ", "address": "123 Collins St, Melbourne VIC 3000", "country": "AU", "region": "VIC", "floor_area_m2": 500, "building_share_pct": 100, "is_active": true, "created_at": "2025-01-15T10:30:00Z" } ], "meta": { "total": 3, "limit": 10, "offset": 0, "has_more": false } }

Parameter

Type

Required

Description

scope

integer

Optional

Filter by scope: 1, 2, or 3.

year

integer

Optional

Filter by reporting year (e.g. 2025).

facility_id

uuid

Optional

Filter by facility ID.

category

string

Optional

Filter by emission category (e.g. "stationary_combustion").

limit

integer

Optional

Results per page. Default 50, max 100.

offset

integer

Optional

Number of results to skip. Default 0.

{ "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "facility_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "reporting_year": 2025, "scope": 1, "category": "stationary_combustion", "subcategory": "natural_gas", "activity_type": "Natural Gas", "quantity": 12500, "unit": "kWh", "description": "Office heating - natural gas", "data_quality": "measured", "emissions_kg_co2e": 2287.5, "market_based_kg_co2e": null, "electricity_source": null, "calculation_method": "activity_based", "period_start": "2025-01-01", "period_end": "2025-12-31", "created_at": "2025-03-10T14:22:00Z", "updated_at": "2025-03-10T14:22:00Z" } ], "meta": { "total": 47, "limit": 5, "offset": 0, "has_more": true } }

Parameter

Type

Required

Description

year

integer

Optional

Reporting year. Defaults to the organization's current reporting year.

{ "data": { "reporting_year": 2025, "total_emissions_kg_co2e": 84523.67, "scope_1_kg_co2e": 12450.30, "scope_2_kg_co2e": 28930.12, "scope_3_kg_co2e": 43143.25, "entry_count": 47, "categories": [ { "category": "stationary_combustion", "scope": 1, "total_kg_co2e": 8230.50, "entry_count": 6 }, { "category": "mobile_combustion", "scope": 1, "total_kg_co2e": 4219.80, "entry_count": 3 }, { "category": "purchased_electricity", "scope": 2, "total_kg_co2e": 28930.12, "entry_count": 12 }, { "category": "business_travel", "scope": 3, "total_kg_co2e": 15200.00, "entry_count": 8 }, { "category": "purchased_goods_services", "scope": 3, "total_kg_co2e": 27943.25, "entry_count": 18 } ] }, "meta": {} }

Parameter

Type

Required

Description

year

integer

Optional

Filter by reporting year.

status

string

Optional

Filter by report status (e.g. "draft", "final").

limit

integer

Optional

Results per page. Default 20, max 100.

offset

integer

Optional

Number of results to skip. Default 0.

{ "data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "reporting_year": 2025, "report_type": "annual", "framework": "ghg_protocol", "status": "final", "total_scope1_kg": 12450.30, "total_scope2_kg": 28930.12, "total_scope3_kg": 43143.25, "total_emissions_kg": 84523.67, "shared_url": "https://app.emisso.app/shared/report/abc123", "created_at": "2025-06-15T09:00:00Z", "updated_at": "2025-06-20T14:30:00Z" } ], "meta": { "total": 2, "limit": 20, "offset": 0, "has_more": false } }

Parameter

Type

Required

Description

id

uuid

Required

The report ID.

{ "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "reporting_year": 2025, "report_type": "annual", "framework": "ghg_protocol", "status": "final", "report_data": { "organization": { ... }, "methodology": { ... }, "scope1": { ... }, "scope2": { ... }, "scope3": { ... }, "summary": { ... } }, "total_scope1_kg": 12450.30, "total_scope2_kg": 28930.12, "total_scope3_kg": 43143.25, "total_emissions_kg": 84523.67, "shared_url": "https://app.emisso.app/shared/report/abc123", "created_at": "2025-06-15T09:00:00Z", "updated_at": "2025-06-20T14:30:00Z" }, "meta": {} }