Equitable Earth Registry API

The Equitable Earth Registry API provides programmatic access to the registry.

Environments

Every endpoint is served under the /api/v2 path of https://eqe.api.gcmu.net.

Getting started

1. Create a credential. An Organisation Administrator creates one under Settings › API Credentials, choosing a name and the role it acts with. The client_id and client_secret are shown once.
2. Request an access token using the client credentials flow described under Authorization.
3. Call the API, sending the token in the Authorization header on every request.

curl "https://eqe.api.gcmu.net/api/v2/projects?page=1&page_size=20" \
  -H "Authorization: Bearer <access_token>"

Resources

Resource	Description	Response format
Projects	Read projects in the registry and register new ones.	CDOP Project_Approach_Details
Issuances	Read issued credits and request new issuances.	CDOP Issuances
Units	Read units held in the registry, registry-wide, by programme, or within your organisation's accounts.	CDOP Unit_Description
Holdings	For a crediting programme: the organisations holding the units it issued, and the units each one holds.	JSON; units as CDOP Unit_Description
Retirements	Request and approve the retirement of units.	JSON
Transfers	Create and approve transfers of units between organisations.	JSON
Accounts	Read the accounts within your organisation.	JSON
Organisations	Read organisations in the registry.	JSON

Every endpoint, with its request and response schemas, is documented in the API Reference.

For example, a crediting programme reads who holds its units, and then one organisation's units with the account that holds each:

curl "https://eqe.api.gcmu.net/api/v2/holdings?page=1&page_size=20" \
  -H "Authorization: Bearer <access_token>"

curl "https://eqe.api.gcmu.net/api/v2/holdings/<organisation_id>/units" \
  -H "Authorization: Bearer <access_token>"

Data format

The Equitable Earth Registry API uses the Carbon Data Open Protocol (CDOP) data model, and responses conform to the CDOP 2.0 JSON Schema. Resources that CDOP does not cover return JSON documents described in the API Reference.

Conventions

Pagination

List endpoints accept page and page_size query parameters. Each response contains the requested items under data and a metadata object with page, page_size, total_count, total_pages, the sorting that was applied, and the attributes available for filtering and sorting. When page_size is omitted, the full result set is returned.

Filtering and sorting

List endpoints accept a filter_by parameter containing a URL-encoded JSON list of terms, each with field, operator and value, and a sorting parameter containing a JSON list of terms, each with by and ascending.

# Example for GET /api/v2/issuances
filter_by=[{"field": "batch_issued_volume", "operator": "GTE", "value": 1000}]
sorting=[{"by": "batch_issued_volume", "ascending": false}]

The supported operators are:

Operator	Meaning	Value
EQ	Equal to	A single value
NE	Not equal to	A single value
GT	Greater than	A single value
GTE	Greater than or equal to	A single value
LT	Less than	A single value
LTE	Less than or equal to	A single value
BE	Between, inclusive	A list of two values: lower and upper bound
NB	Not between	A list of two values: lower and upper bound
IN	Equal to any of the values	A list of values
NIN	Equal to none of the values	A list of values
INCLUDES	A list field contains any of the values	A single value or a list of values

Field names are those of the response document; the metadata.attributes list in each response states exactly which are accepted. A term naming any other field is rejected with status 422.

Errors

The API uses standard HTTP status codes. Error responses carry a JSON body with a detail field describing the problem. A missing or invalid token returns 401, insufficient permissions 403, an unknown resource 404, and a malformed request or query 422.

Support

For integration questions or to report a problem, contact support@gcmu.net.