# Coolset Carbon API Carbon emissions data: search emission factors and categories, read emission calculations and charts, and classify transactions as emissions. Version: 1.0 ## Servers Production server ``` https://developers.coolset.com/api ``` ## Security ### Bearer Our firebase api token, used to authenticate. Bearer prefix required before token Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Coolset Carbon API](https://api.coolset.com/_bundle/carbon-api.yaml) ## emission_calculations ### List aggregated emission chart data - [GET /emission_calculations/charts](https://api.coolset.com/carbon-api/emission_calculations/emission_calculations_charts_list.md): 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. ### List emission line items - [GET /emission_calculations/emissions](https://api.coolset.com/carbon-api/emission_calculations/emission_calculations_emissions_list.md): 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-delete an emission - [DELETE /emission_calculations/emissions/{id}](https://api.coolset.com/carbon-api/emission_calculations/emission_calculations_emissions_delete.md): 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. ### Export emissions as CSV - [GET /emission_calculations/emissions/export](https://api.coolset.com/carbon-api/emission_calculations/emission_calculations_emissions_export_list.md): 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). ### Bulk classify (async) - [PUT /emission_calculations/bulk-classification](https://api.coolset.com/carbon-api/emission_calculations/emission_calculations_bulk-classification_update.md): Accepts multiple independent classification operations. Each operation specifies either emission_filters or transaction_filters (using Django FilterSet lookup syntax) plus classification data. Returns 202 Accepted with per-operation results including count of matched records. ## emission_factors ### Search emission factors - [GET /emission_factors/emission-factors](https://api.coolset.com/carbon-api/emission_factors/emission_factors_emission-factors_list.md): 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. ### Retrieve an emission factor - [GET /emission_factors/emission-factors/{id}](https://api.coolset.com/carbon-api/emission_factors/emission_factors_emission-factors_read.md): 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. ### List emission factor categories - [GET /emission_factors/emission-factor-categories](https://api.coolset.com/carbon-api/emission_factors/emission_factors_emission-factor-categories_list.md): 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. ### Search emission factor categories by keyword - [GET /emission_factors/emission-factor-categories/search](https://api.coolset.com/carbon-api/emission_factors/emission_factors_emission-factor-categories_search_list.md): 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/. ### Retrieve an emission factor category - [GET /emission_factors/emission-factor-categories/search/{id}](https://api.coolset.com/carbon-api/emission_factors/emission_factors_emission-factor-categories_search_read.md): Returns the full details of a single emission factor category by its ID, including its parent category, color, icon, and type flags. ### List greenhouse gas categories - [GET /emission_factors/greenhouse-gas-categories](https://api.coolset.com/carbon-api/emission_factors/emission_factors_greenhouse-gas-categories_list.md): 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.