CarbonGuru API

The CarbonGuru API gives your own software the same carbon analysis as the CarbonGuru website, the browser extension and the AI-agent connection. Every endpoint lives under https://carbonguru.io/v1/, and every request carries an API key.

Get started
API reference
Your API keys

What you can do

  • Analyze products, carts, text and structured items, then read each session, its progress and every item’s footprint.
  • Export and import files on plans that include them: export a session as a file, and get an accounting file back with carbon columns added.
  • Search your history and check your account, plan and analysis totals.
  • Look up reference data: NAICS codes, industry sectors, emission factors and the countries available for analysis.
  • Offset your own footprint: price a footprint or a budget, build a cart and get its checkout link. You complete the purchase in your account.
  • Run a store’s footprints once your account has a connected store: push a catalog, read footprints live by product, choose which footprints show on your storefront, and report paid orders for offsetting.
  • Receive webhooks when an analysis completes or fails, and when a catalog push finishes.

Plans

Every CarbonGuru account includes the API, the free Lead plan too. A request reaches exactly what your plan reaches on the website. Analyses count against your plan’s allowance. File import and export, and a connected store, need a plan that includes them. When a request asks for something your plan does not include, the API answers 402 with a link to upgrade. Compare plans.

Get started

  1. Create a free account on the Get started page, or sign in to the one you have.
  2. Make a key in the API section of your account, at /my-account/api/. Give it only the permissions it needs: carbon:read for history, usage and reference data, carbon:analyze for analyses, carbon:commerce for offsets, and carbon:merchant for a connected store. The key is shown once.
  3. Send your first request. This one returns your account, your plan and your analysis totals, and needs carbon:read:
    curl -H "Authorization: Bearer $CARBONGURU_API_KEY" https://carbonguru.io/v1/usage
  4. Read the API reference for every endpoint, its parameters and its responses.

How it works

  • Each request carries Authorization: Bearer <API key>. Keep keys on your server.
  • Errors are RFC 9457 problem documents, and every response carries an X-Request-ID.
  • Writes accept an Idempotency-Key, and lists page with next_cursor.
  • Three things happen only in your account, never through the API: accepting terms, saving a payment method and switching on automatic offsetting.
  • An account with a connected store can make a test key. It connects the same way and records every order it posts as a preview. Nothing is bought.

The API terms cover every use of the API.