canonical: https://jentic.com/apis/carbonapi.io/carbonapi # CarbonAPI Jentic publishes the only available OpenAPI specification for CarbonAPI, keeping it validated and agent-ready. CarbonAPI is a carbon accounting service that enriches expense, supplier, and freight data with calculated greenhouse-gas emissions. It accepts batches of documents (invoices, receipts, bills) for emissions analysis and batches of structured transactions for category-based emissions estimation, returning kgCO2e values that map to standard carbon-accounting frameworks. Agents can use it to compute the footprint of business spend, freight movements, or supplier activity at scale. ## For AI agents Submit document and transaction batches to calculate greenhouse-gas emissions for spend-based carbon accounting and freight reporting. ## Scope Does not handle real-time emissions, IoT sensor ingest, or carbon offset purchasing - use for batch-based document and transaction emissions calculation only. ## Capabilities - Submit a batch of receipt and invoice documents for emissions analysis - Retrieve the calculated emissions and extracted line items for a document batch by batch ID - Submit a batch of structured transactions for category-based emissions estimation - Retrieve calculated kgCO2e and per-transaction breakdown for a transaction batch by batch ID - Estimate supplier emissions from transactional data using spend-based methodology - Calculate freight emissions for shipping legs included in a transaction batch ## Use cases ### Spend-Based Emissions Reporting Convert a finance system's transaction export into a carbon footprint report. Agents post a transaction batch to POST /v1/transactions/batch, then poll GET /v1/transactions/batch/{batchId} for the calculated kgCO2e per transaction. CarbonAPI applies category-based emission factors and returns results that can be aggregated into Scope 1, 2, and 3 dashboards for sustainability reporting. Example prompt: Post a transaction batch of last month's expenses, poll until processing completes, then return total kgCO2e grouped by category. ### Receipt and Invoice Footprint Analysis Run document-level emissions analysis on receipts and invoices. POST /v1/documents/batch accepts a batch of documents, and GET /v1/documents/batch/{batchId} returns the extracted line items and their calculated emissions. This lets an expense-management or accounting agent attach kgCO2e to every expense without manual categorisation. Example prompt: Upload 50 receipts as a document batch, wait for processing, and return the top three highest-emission line items. ### Freight Emissions for Logistics Reporting Calculate the emissions of freight movements by submitting them as transactions. CarbonAPI supports freight emissions calculation as part of its transaction batch processing, returning kgCO2e per shipping leg. This feeds logistics dashboards and ESG disclosures with auditable freight footprint figures. Example prompt: Submit a transaction batch containing freight legs from origin to destination ports and return total kgCO2e. ### AI Agent Carbon Accounting via Jentic Wire CarbonAPI into an agent through Jentic so a CFO or ESG lead can ask 'what is our footprint for Q1?' and the agent fetches the calculation. Jentic returns the right batch endpoint and schema, holds the API key in its vault, and orchestrates the submit/poll cycle so the agent does not need to maintain integration code. Example prompt: Through Jentic, submit a transaction batch and return the calculated total kgCO2e once results are ready. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/documents/batch | Create a document batch for emissions analysis | | GET | /v1/documents/batch/{batchId} | Get processed document batch results | | POST | /v1/transactions/batch | Create a transaction batch for emissions calculation | | GET | /v1/transactions/batch/{batchId} | Get processed transaction batch results | ## Key resources - **Documents** — Submit receipt and invoice batches for emissions analysis and retrieve results - **Transactions** — Submit structured transaction batches for category-based and freight emissions calculation ## Why Jentic - **Setup:** Wiring CarbonAPI by hand means passing your key in the Authorization header on every call, submitting document and transaction batches, and polling each batchId for results against the api.carbonapi.io host yourself. Through Jentic you install once, import CarbonAPI from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** A batch is created from the request body and read back by its batchId, so you scope by operation: limit the agent to the ones it needs, such as submitting a transaction batch and reading its result, and leave document batch calls out of the allowed set until you want them. - **Credential handling:** Your CarbonAPI key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'calculate emissions for a batch of transactions', and Jentic returns the matching CarbonAPI operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **CarbonDoomsday** — Atmospheric CO2 readings from Mauna Loa for sustainability context. - **Carbon REST API** — Carbon 3D printing manufacturing platform; unrelated to emissions but sometimes confused. - **CarAPI.dev** — Vehicle data API providing VIN decoding and specs that feed vehicle emissions calculations. ## FAQ ### Why is there no official OpenAPI spec for CarbonAPI? CarbonAPI does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CarbonAPI via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the CarbonAPI use? CarbonAPI uses an API key passed in the `Authorization` header on every request. Through Jentic the key is stored encrypted in the credential vault and injected at execution time, so the raw key never appears in the agent's prompt or chat history. ### Can I calculate freight emissions with CarbonAPI? Yes. Freight emissions are handled through the transaction batch endpoint - submit shipping legs as transactions to POST /v1/transactions/batch and CarbonAPI returns the calculated kgCO2e for each leg in the batch result available at GET /v1/transactions/batch/{batchId}. ### Is CarbonAPI synchronous or asynchronous? CarbonAPI is asynchronous and batch-based. POST endpoints accept a batch and return a batchId; the actual emissions calculation runs in the background. Poll the matching GET /v1/{type}/batch/{batchId} endpoint until the batch reports as processed before reading results. ### What are the rate limits for the CarbonAPI? The OpenAPI specification does not declare explicit rate limits. Limits are tied to the plan associated with your API key - keep batch sizes reasonable and back off on 429 responses. Contact CarbonAPI support for the quota tied to your account. ### How do I submit a transaction batch through Jentic? Run `pip install jentic`, then use Jentic's search to find the transaction batch operation with the query "calculate emissions for transactions", load the schema, and execute with your transaction array. Jentic calls POST /v1/transactions/batch, attaches your CarbonAPI key from the vault, and returns the batchId you can poll. ### What's the difference between the documents and transactions endpoints? The /v1/documents/batch endpoints take unstructured receipts and invoices and extract line items before calculating emissions. The /v1/transactions/batch endpoints take already-structured transaction records (amount, category, supplier) and apply category-based emission factors directly. Use documents when starting from PDFs/images, and transactions when starting from your finance system. ### Can I limit what my agent is allowed to do with the CarbonAPI? Yes. Because you run Jentic One yourself, your own rules decide which CarbonAPI operations and credentials the agent may use, so you scope access by operation. CarbonAPI creates a batch from the request body and reads it back by its batchId, which means you can allow the agent to submit a transaction batch (POST /v1/transactions/batch) and read its result (GET /v1/transactions/batch/{batchId}) while leaving the document batch calls out of the allowed set. Your CarbonAPI key stays with your instance and is injected only when a permitted operation runs, so the agent can only call the endpoints you have approved.