GCMU Registry API

The GCMU Registry API provides programmatic access to the GCMU registry.

Environments

Production requests are made against https://api.gcmu.net. Every endpoint is served under the /api/v2 path.

A sandbox environment is available at https://sandbox.api.gcmu.net for testing. It is a separate tenant with its own credentials; production credentials are not accepted there.

Getting started

1. Obtain credentials. Contact support@gcmu.net to have a client_id and client_secret issued for your organisation.
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://api.gcmu.net/api/v2/projects?page=1&page_size=20" \
  -H "Authorization: Bearer <access_token>"

Resources

Resource	Description	Response format
Projects	Read projects registered with GCMU 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
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 registered with GCMU.	JSON

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

Data format

The GCMU 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 credentials, integration questions or to report a problem, contact support@gcmu.net.