Single queries are open: you can pull a single record, its score, and sector/benchmark data from read-only (GET) endpoints, without an account. The full list with scores (/gated/) requires sign-in and is not yet generally available — write to us for access. There is no API key and no enforced rate limit today. Company report source links are not part of the open record files: a record carries the source host, the document's SHA-256 hash and page references, and the link itself opens on the record page for signed-in users with a company email address (3 distinct documents per day). Links to official registries stay in the open files.
Bulk access: the universe is served as static shard files (/api/recordshard/{3hex}.json and the parallel badgeshard / verifyshard / trendshard sets). They are open and require no sign-in — this is how the explorer itself is drawn. We do not treat their existence as a secret: if you need the whole corpus, use them, cache on your side, and credit Carbonbench. What we do ask for by agreement is commercial redistribution (reselling or republishing the dataset as a product) — contact us.
Write access exists at only two points: claiming a profile (claim) and filing a dispute; both require corporate email verification (see Privacy).
When republishing data pulled from the API or using it in a product, credit "Carbonbench" as the source and, where possible, link to the relevant record. Details: Terms of Use.
Stay within a reasonable request frequency. The universe files are served as single static documents — there are no limit/offset parameters, and adding them has no effect. Download a file once, cache it on your own side, and re-fetch it only when you expect it to have changed, rather than pulling it repeatedly at short intervals.
The API is subject to the same "as is" principle as the rest of the product — no guarantee of continuity or backward compatibility is given. Scoring formulas are updated in two windows per year (January/July); field names and endpoint shapes may also change over time. For critical integrations, record the version/date information (the version field of the records).
curl https://carbonbench.org/api/record/{record_id}.json
Pass a record ID in place of {record_id} — click a row in the Universe and it appears in the address bar after ?r=. The response is an object whose records key holds the record: its canonical form (records.payload_canonical), its SHA-256 seal, the results of the verification rules, and the ledger entry — so you can recompute the seal yourself. For records whose source.url_gated is true (company-report records), the canonical text and the source link are withheld from this response; the sha256, seal and ledger entry are unchanged, and the canonical text is released on the record page together with the source document for signed-in users with a company email address. Depending on the record, the object may also carry projeksiyon, vcmap and tesvik keys; treat any key you do not recognize as optional. Several field names are non-English data keys, kept unchanged for compatibility — the most common (jq-style paths): .records.dogruluk = the Accuracy Estimate block, .records.gecmis = score history (.seffaflik = transparency, .hedef = target quality), .records.sinir = organizational boundary, .projeksiyon = emissions projection, .tesvik = supplier-incentive simulation, .vcmap = value-chain map; in list files, .kaynak = extraction source (also served as .source). The methodology lists the accuracy fields one by one.
| Endpoint | What it returns |
|---|---|
| /api/record/{record_id}.json | A single sealed record (seal + verification log; canonical text except for gated company-report records) |
| /api/stats.json | Universe counters and ledger integrity |
| /api/companies-lite.json | Company directory — name, sector, year (score not included) |
| /api/sectors.json | Sector list — sector (data key), label_en (display name), id, n |
| /api/recordshard/{3hex}.json | Bulk: 4,096 shard files, each holding several full records (the same objects as /api/record/…); download once and cache |
| /press-data/data.json | Aggregate press data (also sector_medians.csv, score_distribution.csv) |
| /api/benchmark/overview.json | EXIOBASE benchmark groups (detail: /api/benchmark/{regions|band|trend}/{i}.json) |
| /badge/{code}.svg | Badge (English) — also .strip.svg, .card.svg, .json; {code} is the 10-character verification code |
| /v/{code} | Badge verification page (HTML) |
| /gated/api/companies.json | Reserved for the full list with scores — not generally available; answers 401 |
This list covers the endpoints we document and support. The site also serves derived files that the web interface consumes directly; those are not part of this contract, are not documented, and may change or disappear without notice — please do not build on them. No OpenAPI/Swagger interface is published, and no schema guarantee is given (see below).
The Carbonbench API is read-only. Single records and the static shard files are open without an account; the full scored list requires sign-in and is not yet generally available; commercial redistribution is by agreement. Reuse requires attribution ("Carbonbench" + link). There is no pagination — download a file once and cache it on your side; no OpenAPI specification is published. The API is provided as-is with no uptime or backward-compatibility guarantee; scoring formulas update on two fixed windows per year (January/July). Example request: curl https://carbonbench.org/api/record/{record_id}.json.