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, then either build a cart and get its checkout link, or, once you switch on API purchasing in your account, buy offsets and removals directly, one time or monthly, charged to your saved payment method. See, pause, resume and cancel monthly purchases through the API too.
  • 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, when a catalog push finishes, and when an API purchase is paid, its charge is declined or its certificate is issued.

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.
  • Four things happen only in your account, never through an API key: accepting terms, saving a payment method, switching on automatic offsetting and switching on API purchasing.
  • 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.