Karbonet API

Push activity data from your ERP, utility bills or scripts, and read your anchored carbon position. Every record is calculated with the factor valid on its activity date and its hash is anchored on-chain.

Authentication

Create a token under Profile → API Tokens and send it as a bearer header. Tokens carry read or read + write access, scoped to your company. The account's e-mail address must be verified; unverified accounts receive 403 {"error":"email_unverified"}.

curl https://karbonet.com/api/v1/summary \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Plans & limits

API access and webhooks depend on your billing tier; the free trial includes them with trial-sized caps. Limits are per company, not per token. Every value below is read from the live billing configuration.

API limits per billing tier
Tier	API	Tokens	Requests / min	Bulk calls / min	Rows per bulk call	Webhook endpoints	Records
Starter	No	—	—	—	—	—	200
Exporter	Yes	3	120	20	100	2	1,000
Scale	Yes	10	300	50	500	10	3,000
Enterprise	Yes	Unlimited	600	100	500	Unlimited	Unlimited
Prova gratuita	Yes	1	60	10	50	1	100

Records is a rolling allowance (per 30 days on monthly billing, ×12 per 365 days on annual billing; a total for the trial). Bulk calls share the request budget: bulk calls per minute = requests per minute ÷ 6. Accounts without a tier limit fall back to 60 requests/minute.

402 Payment Required. When a company has no API entitlement (a tier without API access, or a lapsed subscription — lapsed workspaces are read-only) every v1 request returns 402 {"error":"billing_required","message":…,"state":…,"upgrade_url":…}. When a write would exceed the record allowance or the bulk row cap, the request returns 402 {"error":"limit_reached","key":…,"limit":…,"used":…,"upgrade_url":…} and nothing is stored. Rate limits return 429 Too Many Requests with Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers; 429 {"error":"busy"} means a concurrent write for the same company is still being counted — retry after a moment. Need more? Compare tiers or contact us.

No sandbox

There is no test mode. Records created through the API are real: they count against your allowance and their hash is anchored on-chain permanently. The API has no delete endpoint — integrate against a separate test company (its own trial) and remove test entries in the app under Emissions.

Endpoints

API v1 endpoints
Method	Path	Description
GET	/api/v1/me	Token owner + company profile.
GET	/api/v1/summary	Carbon position: gross/net, Scope 1–3, dual Scope 2 (location + market YTD), projection, data quality.
GET	/api/v1/activities	Accepted activity types with units, factors, GWP basis.
GET	/api/v1/emissions	Paginated entries. Filters: `from`, `to`, `scope`, `activity_type`, `status`, `per_page`.
GET	/api/v1/emissions/{id}	One entry, incl. record hash, tx hash and explorer URL.
POST	/api/v1/emissions	Record activity data (`write` tokens). CO₂e is computed server-side and the record is queued for on-chain anchoring.
POST	/api/v1/emissions/bulk	Batch write as `{"entries": [...]}` — up to your tier's rows per call (technical maximum 500), all-or-nothing with per-row validation errors.

Webhooks

Configure endpoints under Profile → Webhooks to receive HMAC-signed POSTs on entry.verified, report.ready and report.anchored. The X-Karbonet-Signature header is the lowercase hex HMAC-SHA256 of the raw request body with your endpoint's signing secret; recompute it and compare in constant time before parsing the JSON. The former X-GreenLedger-Event / X-GreenLedger-Signature headers are still sent with the same values and stay valid, but they are deprecated — move your handler to the X-Karbonet-* pair. Endpoints must be HTTPS, any 2xx counts as delivered, deliveries may arrive more than once (dedupe on event + record id), and an endpoint auto-disables after 20 consecutive failures.

Recording an emission

curl -X POST https://karbonet.com/api/v1/emissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "electricity",
    "quantity": 12500,
    "occurred_on": "2026-07-31",
    "description": "July grid consumption"
  }'

The response includes the computed co2e_kg (using your country's grid factor when available) and the canonical record_hash. Once anchored, tx_hash, block_number and explorer_url are filled in. Anyone can check a record by its record hash (not the transaction hash) on the public verification page: https://karbonet.com/it/verify/{record_hash} — no account needed.