# BeZero Carbon

> BeZero Carbon is a global carbon ratings agency for the Voluntary Carbon Market. It publishes an
> independent eight-point rating (AAA to D, plus Withdrawn) expressing the likelihood that a given
> carbon credit achieves a tonne of CO2e avoided or removed from the atmosphere, along with risk
> factor scores and project reference data. The BeZero Ratings API (v3) delivers that data as JSON
> over HTTPS, authenticated with OAuth 2.0 client credentials.

Generated by API Evangelist from BeZero's published OpenAPI and public site. BeZero publishes no
llms.txt of its own (https://bezerocarbon.com/llms.txt returned 404 on 2026-08-07).

## APIs

- [BeZero Ratings API](https://api-docs.bezerocarbonmarkets.com/): Ratings, rated projects and premium risk factor scores. Base URL `https://api.bezerocarbonmarkets.com/v3`. OpenAPI 3.0.0, four read-only GET operations.

## Operations

- `listRatings` — `GET /ratings`: paginated list of ratings (100/page), ordered by `dataLastUpdatedAt` then `projectID`. Filter with `changedSince` for incremental sync. Scope `bcm/v3.ratings:list`.
- `getRatingDetails` — `GET /ratings/{ratingID}`: summary analysis for one rating. **Deprecated by BeZero** — `summaryAnalysis` is now returned inline by `listRatings`. Scope `bcm/v3.ratings:details`.
- `getRiskFactors` — `GET /ratings/{ratingID}/risk-factors`: **Premium.** Additionality, carbon accounting and permanence scores on an `aaa`..`d` scale. Scope `bcm/v3.ratings:riskFactors`.
- `listProjects` — `GET /projects`: paginated list of rated projects (100/page) with accreditor, registry ID, name, sector group, sector, sub-sector and ISO 3166-1 alpha-3 location. Scope `bcm/v3.projects:list`.

## Semantics an agent needs

- **Auth**: OAuth 2.0 client credentials. Token endpoint `https://login.bezerocarbonmarkets.com/oauth2/token`. Client ID and secret are issued by BeZero under a commercial agreement; there is no self-service signup.
- **Rating scale**: `AAA` `AA` `A` `BBB` `BB` `B` `C` `D` `Withdrawn`. Risk factor scores use lowercase `aaa`..`d` (and may be an empty string when unscored).
- **Watch status**: `onRatingsWatch` is a boolean. When true the rating is under review and may be upgraded, downgraded or reaffirmed. BeZero requires the watch status to be shown next to the rating for as long as it is set.
- **Withdrawn**: a rating may be withdrawn when a project stops meeting eligibility criteria; the API returns `Withdrawn` rather than dropping the record.
- **Vintages**: the rating applies only within the `vintages[].startDate`/`endDate` range returned.
- **Versioning**: opt in with the `Accept-API-Version` header. `3.0` (default) returns only the first published rating per project; `3.1` returns multiple ratings per project. An unsupported value is rejected with 400. The resolved version is echoed back on the response.
- **Pagination**: `page` query parameter; `links.nextPage` / `links.prevPage` on the response; `links.queryLatestChanges` gives the `changedSince` URL to use on the next poll.
- **Rate limit**: 1000 requests per minute. Over it, 429 with a `Retry-After` header (1 minute).
- **Errors**: 400 unsupported version, 403 unauthorised (also returned when the token lacks the endpoint's scope), 404 rating not found, 429 rate limit exceeded. Responses are plain JSON, not RFC 9457 problem+json.

## Specs and artifacts

- [OpenAPI 3.0.0](openapi/bezero-carbon-ratings-openapi.yml)
- [Authentication profile](authentication/bezero-carbon-authentication.yml)
- [OAuth scopes](scopes/bezero-carbon-scopes.yml)
- [API conventions](conventions/bezero-carbon-conventions.yml)
- [Error catalog](errors/bezero-carbon-problem-types.yml)
- [Lifecycle and deprecation policy](lifecycle/bezero-carbon-lifecycle.yml)
- [Data model](data-model/bezero-carbon-data-model.yml)
- [Agent skills](skills/_index.yml)

## Docs

- [API reference](https://api-docs.bezerocarbonmarkets.com/)
- [v2 to v3 migration guide (PDF)](https://api-docs.bezerocarbonmarkets.com/bezero-api-migration-guide-v3.pdf)
- [Ratings methodology and resources](https://bezerocarbon.com/ratings/resources)
- [Publicly available ratings](https://bezerocarbon.com/ratings/listings)
- [Data products](https://bezerocarbon.com/products/data)
- [Ratings governance and processes](https://bezerocarbon.com/about/governance)
- [Product-specific terms (API terms)](https://legal.bezerocarbon.com/legal-hub/product-specific-terms-ffc0b2c9)
- [Insights (blog)](https://bezerocarbon.com/insights)

## Contact

- API engineering: engineering@bezerocarbon.com
- General: contact@bezerocarbon.com