Coolset Carbon API (1.0)

This is the primary endpoint for carbon emission statistics — use it for virtually all requests where a user wants insight into their carbon footprint (totals, breakdowns, trends, comparisons). Returns emission data aggregated by one or more dimensions (date, scope, category, etc.) for charting and analysis. Use the 'group_by' parameter to control how emissions are bucketed, and standard emission filters (accounting_date__gte, accounting_date__lte, scope, category, etc.) to narrow the dataset. Results include total CO2 in kg, transaction counts, and optional intensity metrics when a date range is provided.

Returns a paginated list of individual carbon emission records for the authenticated company. Each record includes the emission source, CO2 amount in kg, accounting date, scope, category, vendor, and emission factor details. Use filters to narrow by date range (accounting_date__gte/lte), scope, category, or search by title/description/vendor. Supports ordering by accounting_date, title, vendor_name, volume, or co2_kg.

Soft-deletes a single emission. Spanning siblings sharing the same emission_group_id and tag-along emissions cascade automatically. Tag-alongs and consolidated emissions cannot be deleted directly.

Downloads all matching emission records as a streaming CSV file. Includes emission factor details and company tags. Accepts the same filters as the emissions list endpoint (accounting_date__gte/lte, scope, category, search, ordering).

Accepts multiple independent classification operations. Each operation specifies either emission_filters or transaction_filters (using Django FilterSet lookup syntax) plus classification data. To create a single activity-based emission, provide activity_data and omit both filter fields.

Returns 202 Accepted with per-operation results including count of matched records.

Returns a paginated list of emission factors available to the authenticated company. Emission factors define the CO2e multiplier for a given spend or activity type. Use the 'search' parameter to search by title, description, or slug. Filter with query parameters:

• region: ISO country code (e.g. 'GB', 'US', 'DE')
• year: Publication year of the emission factor (integer)
• sub_category: ID of the sub-category
• sub_category__parent: ID of the parent (top-level) category
• classification_category: ID of the classification category
• is_activity_based: true for activity-based factors, false for spend-based
• company__isnull: true for global factors only, false for company-specific only
• source: Filter by source name (partial match, use source__icontains)
• company__exact: Filter by company ID
• category: Deprecated alias for sub_category (prefer sub_category) Supports ordering by: slug, title, year, region, category, sub_category, kg_co2e_multiplier.

Returns the full details of a single emission factor by its ID. Includes the CO2e multiplier value and unit, emission category, classification category, company, region, year, source, and whether it is activity-based.

Returns a paginated list of emission factor categories organized in a 3-level hierarchy: top-level scope → sub-category → classification category. Use 'search' to search by title, description, or slug. Filter with query parameters:

• parent: ID of the parent category (omit to get all levels)
• parent__isnull: true to return only top-level categories
• is_classification_category: true to return only leaf-level classification categories (the IDs used in bulk-emission-classification)
• is_tag_along: true to return tag-along categories only
• requires_manual_input: true to return categories requiring manual input
• mandatory: true to return mandatory input categories
• ghg_categories: GreenhouseGasCategory ID(s) — repeat to filter by multiple (deduplicated union) Supports ordering by title and slug.

Performs a fuzzy full-text search on emission factor categories using trigram similarity. This is the recommended endpoint for finding the right category when classifying an emission. Parameters:

• search: Keyword to search for in category titles. Results are ranked by similarity score.
• type: Filter by emission type. One of: 'spend_based' (default), 'activity_based', or 'both'. Use 'spend_based' when classifying a financial transaction; use 'activity_based' when classifying a physical activity (e.g. km driven, kWh consumed). Supports ordering by: title, similarity (default: similarity descending). Tip: use the returned category 'id' as classification_category_id when creating an emission via PUT /emission_calculations/bulk-emission-classification/.

Returns the full details of a single emission factor category by its ID, including its parent category, color, icon, and type flags.

Returns a paginated list of GHG categories used to classify emission factor categories under the GHG Protocol scopes. Use 'search' to search by title. Filter with query parameters:

• scope: GHG scope (1, 2, or 3)
• emission_direction: 'upstream' or 'downstream' (scope 3 only); pass 'null' for categories with no direction Supports ordering by title.