Skip to main content
CarbonMeld CarbonMeld Carbon Observatory
Premium

CarbonMeld API (v1)

Last updated:

REST API v1 with Premium: project records, filtered lists and market stats. Bearer key, 300 requests per day per key.

Open your account page · Premium details and pricing

What the API returns

Read the project data that CarbonMeld holds: project lists, market statistics and individual records with available ratings and document-based analysis. A project record combines public data with Premium details when available. Ratings and analysis depend on the published record; Premium does not create missing analysis.

How the rating works

Get your key

Sign in on your account page with active Premium access, then generate an API key. Copy it when shown: it is displayed only once. Regenerating revokes your previous key. The key stops authenticating when your Premium access ends and works again once you have access again, unless revoked.

Open your account page

Authentication

Send the key in the Authorization header on every request. Keys start with cmk_ followed by 64 lowercase hexadecimal characters. The examples use a placeholder: replace it locally with your own key and keep that key private. An application can instead sign in with your CarbonMeld account (OAuth 2.1 with PKCE, scope carbonmeld.read) and send the access token it receives the same way.

Authorization: Bearer cmk_YOUR_KEY_HERE

Machine-readable description of this API (OpenAPI 3.1): https://carbonmeld.com/api/v1/openapi.json

Endpoints

Every request of the API. Where a row names an MCP tool, the request returns the same object as that tool; the OpenAPI description gives each request's parameters and responses.

RequestResponse
GET /api/v1/statsMarket statistics from the current export, including project and registry counts and updated_at. These are indexed projects, not a count of completed assessments.
GET /api/v1/projectsFiltered project list: updated_at, total (after filtering), limit, offset and projects.
GET /api/v1/projects/<id_or_slug>One project by registry code, canonical slug or alias. Premium details, when available, share the daily project quota.
POST /api/v1/projects/batchSeveral project records in one call: the same record as get_project for each id, in the ids' order, with a per-id error where one id fails. Each record found uses the shared project quota, exactly as get_project does. Ids past the invocation's request limit come back retryable and unopened (no quota used): ask again for those ids.Same object as the MCP tool get_projects
GET /api/v1/projects/<id_or_slug>/pageWhat a project's page says beyond the record, as the page shows it: its notices, «How this analysis was made», similar projects, the PDF report's address and the project's positions in the leaderboards.
GET /api/v1/projects/<id_or_slug>/ranksA project's positions in the leaderboards, as its page shows them.
GET /api/v1/methodologies/<code>One methodology as its CarbonMeld page shows it: identity card with sources; how methodology v3 reads projects of this type (the v2.2 rules that stay the same, the changed ones as the v3 rules they became, and a link to the v2.2 rules as they were); version history and transitions; its projects (a ranking of v3 ratings, or a list); the page's URL.Same object as the MCP tool get_methodology
GET /api/v1/standards/<code>One standard as its CarbonMeld page shows it: identity card with sources; how methodology v3 reads projects of this standard (the v2.2 programme rules that stay the same, the changed ones as the v3 rules they became, and a link to the v2.2 rules as they were); the methodologies it issues and its projects use; its projects (a ranking of v3 ratings, or a list); the page's URL.Same object as the MCP tool get_standard
GET /api/v1/rankings/<dimension>[/<value>]The leaderboards as the site shows them: a dimension's boards with their counts and averages, or one board's projects ranked by rating (at least 5 rated), with the page's URL. Sector boards group projects by the sector they were rated under.Same object as the MCP tool get_ranking
GET /api/v1/developers/<slug>One project developer as its CarbonMeld page shows it: its numbers of projects, of projects with a methodology v3 rating and of projects with a registry status of rejected, withdrawn, terminated, suspended or issuance denied, its standards and countries, and its projects in the page's order, each with registry code, country, registry status, its rating as the lists show it (a methodology v3 rating with its band, a v2.2 score labelled v2.2, or «Too early to rate» / «Not yet assessable» / «No public grade applies yet» / «Rating not shown»; marked provisional while re-assessed) or analysis state, and project URL, with the page's URL. There is no company-level rating; ambiguous names require clarification.Same object as the MCP tool get_developer
GET /api/v1/buyers/<slug>Public retirement records for an organisation as its CarbonMeld page shows them: tonnes, retirements, the quality of what it retired, its projects with the tonnes retired from each and each project's current rating, and its latest retirements. A retirement beneficiary is not necessarily the purchaser; ambiguous names require clarification.Same object as the MCP tool get_buyer
GET /api/v1/ccp-trackerThe ICVCM CCP tracker as the site shows it: the Integrity Council's methodology assessments with their status and the number per status, and for each assessment the number of that programme's projects CarbonMeld tracks under the methodology code (every version: not a count of CCP-labelled credits) and its leaderboard, with the table's source and fetch date.Same object as the MCP tool ccp_tracker
GET /api/v1/corsiaCORSIA registry labels by registry and phase as the site shows them, with the highest-rated First Phase projects and each registry's average rating, from the projects' current ratings. Balances are unretired units of every vintage, not CORSIA-eligible units.Same object as the MCP tool corsia_supply
GET /api/v1/claims-changesThe last 30 days CarbonMeld recorded: official rule-setter notices (ICVCM, Verra, Gold Standard, SBTi and others; publisher, title, link, day) and registry labels added to or removed from projects (with each project page's URL), plus the count of projects per kind of label change over the whole window.Same object as the MCP tool what_changed
GET /api/v1/methodCarbonMeld's rating method as /methodology/ shows it: methodology v3, the document-based rating. Without arguments: the page's sections, the method's version, the four dimensions with their weights and the address of the archived v2.2 rules. A section: its text as the page shows it, with the rule ids in it and one row for each rule card. A rule by its id (A-START, Q-FNRB-ABOVE) or by the key of its card: its name, what it does, each effect and its figure, since when it applies, its source and the source's own words. A v2.2 id (CM-…) gives that rule as v2.2 had it and its place in v3: the same, changed (with the v3 rule it became) or dropped. A dimension (additionality, quantification, permanence, claim_safety, overall): the rules that act on it, in pages (limit, offset; next_offset). Methodology v3 has no criteria.Same object as the MCP tool get_method
GET /api/v1/articlesSearch CarbonMeld's articles in English, Chinese or Japanese as the site's article index lists them: by words (each in the title, the summary or a tag), by tag (the articles of the site's page for that tag) and by date. Returns the number of matches and one page of them, newest or oldest first (next_offset when more remain): title, date, summary, tags, category and URL. No match is an empty list, not an error.Same object as the MCP tool search_articles
GET /api/v1/portfolioYour own portfolio (My portfolio) as its page shows it: the projects you saved, each with its rating as the lists show it (a methodology v3 rating with its band, a v2.2 score labelled v2.2, or «Too early to rate» / «Not yet assessable» / «No public grade applies yet» / «Rating not shown»; marked provisional while re-assessed), analysis state, registry status, vintages, listings and analysis date; for a project read under methodology v3 its negative facts, for a v2.2-scored one its red flags, labelled v2.2; the dimension values only when every rated project is on the same methodology version; the average of the v3 ratings; two separate counts, the negative facts of the projects read under methodology v3 and the red flags of the v2.2-scored projects; the changes left this week; and the change alerts of the last 30 days for these projects. Read only: saving and removing projects is done on the site. It uses none of the daily project quota.Same object as the MCP tool my_portfolio
POST /api/v1/check-offerCompare pasted offer text with recorded registration, vintages, quantities, claims and developer. This does not confirm ownership or availability of a specific serial number.Same object as the MCP tool check_offer
POST /api/v1/mcpThe MCP server for AI assistants (JSON-RPC 2.0 over HTTP POST).MCP guide

Project list parameters

ParameterAccepted values
registryStandard code present in the data, case-insensitive (for example VCS). An unknown value returns 400 with the valid values.
min_scoreNumber from 0 to 10. When provided, even 0 excludes projects without a numeric score. Omit to include unscored projects.
qWords that must all appear in the project's name, registry code, country, methodology or sector (up to 100 characters).
countryISO 3166-1 alpha-2 code (for example KE) or a country name (for example Kenya). An unknown value returns 400.
methodologyMethodology catalogue code, case and spaces ignored (for example VM0048). An unknown value returns 400 with close codes.
sectorProject type: arr, biochar, biogas, biomass, blue_carbon, cookstoves, dac, industrial, industrial_gases, methane, other, redd, renewable_energy, soil_carbon, water. An unknown value returns 400.
limitDecimal integer from 1 to 200; default 50.
offsetNon-negative decimal integer; default 0.

Limits and fair use

  • 300 requests per day per key by default, shared by REST and MCP.
  • 30 different Premium projects per day, shared across the website, PDF reports, REST and MCP. Reopening the same project that day counts once. Portfolio projects and projects unlocked for you are exempt; public-only records do not consume this project quota.
  • With Pro: 1,000 requests per day per key and 300 different projects per day; everything else as above.
  • 20 offer checks per day per account, shared with the website offer checker.

Daily counters reset at 00:00 UTC. A burst limit also applies: 120 requests per minute per IP. List and statistics requests count towards the request limit, not the Premium project quota.

Errors

StatusMeaning and next step
400Invalid project identifier or list parameter. Check the error message and accepted values.
401Missing, invalid or revoked key, or no active Premium access. Check the Authorization header and your account.
403A sign-in access token whose account has no active Premium access. Check your account.
404Project not found. Check the registry code or slug.
429Request, burst or project limit reached. Respect the Retry-After response header.
503The project is being updated. Respect Retry-After and retry later.

Example requests

Read a filtered list, then request one record by registry code. The second request can consume a Premium project view.

curl 'https://carbonmeld.com/api/v1/projects?registry=VCS&min_score=7&limit=5&offset=0' \
  -H 'Authorization: Bearer cmk_YOUR_KEY_HERE'

curl 'https://carbonmeld.com/api/v1/projects/VCS-1318' \
  -H 'Authorization: Bearer cmk_YOUR_KEY_HERE'
View the example project: VCS-1318

What the API does not do

This is read access to CarbonMeld data. It does not integrate registry issuance or MRV workflows, issue or transfer credits, or validate ownership of individual serial numbers. Registry labels and recorded quantities describe the records we hold; they are not a guarantee about an offer.

Terms

Read the usage conditions and the explanation of the rating methodology before using the data in your work.

Terms of Use

Use it from an AI assistant

The MCP server uses the same API key and quotas.

MCP guide

Configuration examples and MCP Registry entry on GitHub