External API

External-facing endpoints for marketplace integration

Get Account Summary

get

https://dev.granularregistry.com/apihttp://localhost:8000

/external/accounts/{account_id}/summary

Get high-level account statistics including certificate counts and project information

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication using Bearer token format. Example: Authorization: Bearer gcreg_2fCeA78CA62644eB55B0A36249245A27

Path parameters

account_idintegerRequired

Account ID to query

Example: 1

Responses

200

Account summary data

application/json

account_idintegerRequiredExample: 1

total_gcsintegerRequired

Total certificate quantity in Wh

Example: 10835299996

active_gcsintegerRequired

Active certificate quantity in Wh

Example: 10835299996

cancelled_gcsintegerRequired

Cancelled certificate quantity in Wh

Example: 0

expired_gcsintegerRequired

Expired certificate quantity in Wh

Example: 0

total_projectsintegerRequired

Number of unique projects (devices)

Example: 1

last_issuance_datestring · date-time · nullableOptional

Date of most recent certificate issuance

Example: 2024-01-01T11:05:00Z

401

Authentication failed - invalid or missing API key

application/json

403

Access denied - insufficient permissions or account access

application/json

404

Resource not found

application/json

get

/external/accounts/{account_id}/summary

HTTPcURLJavaScriptPython

GET /api/external/accounts/{account_id}/summary HTTP/1.1
Host: dev.granularregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "account_id": 1,
  "total_gcs": 10835299996,
  "active_gcs": 10835299996,
  "cancelled_gcs": 0,
  "expired_gcs": 0,
  "total_projects": 1,
  "last_issuance_date": "2024-01-01T11:05:00Z"
}

Get Account Certificates

get

https://dev.granularregistry.com/apihttp://localhost:8000

/external/accounts/{account_id}/certificates

Get detailed certificate listings for a specific account with filtering options

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication using Bearer token format. Example: Authorization: Bearer gcreg_2fCeA78CA62644eB55B0A36249245A27

Path parameters

account_idintegerRequired

Account ID to query

Example: 1

Query parameters

statusstring · enumOptional

Filter by certificate status

Example: ACTIVEPossible values:

device_idintegerOptional

Filter by device ID

Example: 1

limitinteger · min: 1 · max: 1000Optional

Maximum number of certificates to return

Default: 100Example: 10

offsetintegerOptional

Number of certificates to skip

Default: 0Example: 0

Responses

200

List of certificates

application/json

certificate_idstringRequired

ULID identifier for the certificate bundle

Example: 01K15XSS23Z1R1NG90K0WZVKN0

issuance_idstringRequired

Unique issuance identifier

Example: SOL-2024-000001-SOLAR-DEMO-TX-00

bundle_quantityintegerRequired

Certificate quantity in Wh (1 MWh = 1,000,000 Wh)

Example: 1000000

certificate_statusstring · enumRequiredExample: ACTIVEPossible values:

production_startstring · date-timeRequired

Start of production period

Example: 2024-01-01T00:00:00Z

production_endstring · date-timeRequired

End of production period

Example: 2024-01-01T01:00:00Z

energy_sourcestringRequired

Type of energy source

Example: solar_pv

device_idintegerRequiredExample: 1

device_namestring · nullableOptionalExample: Demo Solar Farm - Main Array

device_locationstring · nullableOptionalExample: Austin, TX

device_technologystring · nullableOptionalExample: solar_pv

device_capacityinteger · nullableOptional

Device capacity in watts

Example: 100000

country_of_issuancestringRequiredExample: USA

issuing_bodystringRequiredExample: GC Registry

is_storagebooleanRequiredExample: false

expiry_datestring · date-timeRequiredExample: 2026-01-01T11:00:00Z

created_atstring · date-timeRequiredExample: 2024-01-01T11:00:00Z

401

Authentication failed - invalid or missing API key

application/json

403

Access denied - insufficient permissions or account access

application/json

404

Resource not found

application/json

get

/external/accounts/{account_id}/certificates

HTTPcURLJavaScriptPython

GET /api/external/accounts/{account_id}/certificates HTTP/1.1
Host: dev.granularregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "certificate_id": "01K15XSS23Z1R1NG90K0WZVKN0",
    "issuance_id": "SOL-2024-000001-SOLAR-DEMO-TX-00",
    "bundle_quantity": 1000000,
    "certificate_status": "ACTIVE",
    "production_start": "2024-01-01T00:00:00Z",
    "production_end": "2024-01-01T01:00:00Z",
    "energy_source": "solar_pv",
    "device_id": 1,
    "device_name": "Demo Solar Farm - Main Array",
    "device_location": "Austin, TX",
    "device_technology": "solar_pv",
    "device_capacity": 100000,
    "country_of_issuance": "USA",
    "issuing_body": "GC Registry",
    "is_storage": false,
    "expiry_date": "2026-01-01T11:00:00Z",
    "created_at": "2024-01-01T11:00:00Z"
  }
]

Get Account Projects

get

https://dev.granularregistry.com/apihttp://localhost:8000

/external/accounts/{account_id}/projects

Get project (device) information for an account including certificate statistics

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication using Bearer token format. Example: Authorization: Bearer gcreg_2fCeA78CA62644eB55B0A36249245A27

Path parameters

account_idintegerRequired

Account ID to query

Example: 1

Responses

200

List of projects

application/json

device_idintegerRequiredExample: 1

project_namestring · nullableOptionalExample: Demo Solar Farm - Main Array

technology_typestring · nullableOptionalExample: solar_pv

capacityinteger · nullableOptional

Device capacity in watts

Example: 100000

locationstring · nullableOptionalExample: Austin, TX

production_start_datestring · date-time · nullableOptionalExample: 2023-01-01T00:00:00Z

total_certificates_issuedintegerRequired

Total certificate quantity issued in Wh

Example: 10835299996

active_certificatesintegerRequired

Active certificate quantity in Wh

Example: 10835299996

earliest_production_periodstring · date-time · nullableOptionalExample: 2024-01-01T00:00:00Z

latest_production_periodstring · date-time · nullableOptionalExample: 2024-01-01T11:05:00Z

401

Authentication failed - invalid or missing API key

application/json

403

Access denied - insufficient permissions or account access

application/json

404

Resource not found

application/json

get

/external/accounts/{account_id}/projects

HTTPcURLJavaScriptPython

GET /api/external/accounts/{account_id}/projects HTTP/1.1
Host: dev.granularregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "device_id": 1,
    "project_name": "Demo Solar Farm - Main Array",
    "technology_type": "solar_pv",
    "capacity": 100000,
    "location": "Austin, TX",
    "production_start_date": "2023-01-01T00:00:00Z",
    "total_certificates_issued": 10835299996,
    "active_certificates": 10835299996,
    "earliest_production_period": "2024-01-01T00:00:00Z",
    "latest_production_period": "2024-01-01T11:05:00Z"
  }
]

Get Marketplace Certificates

get

https://dev.granularregistry.com/apihttp://localhost:8000

/external/marketplace/certificates

Get certificates optimized for marketplace trading (requires TRADING_USER role or higher)

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication using Bearer token format. Example: Authorization: Bearer gcreg_2fCeA78CA62644eB55B0A36249245A27

Query parameters

energy_sourcestring · enumOptional

Filter by energy source

Example: windPossible values:

countrystringOptional

Filter by country of issuance

Example: USA

min_vintageintegerOptional

Minimum vintage year

Example: 2024

max_vintageintegerOptional

Maximum vintage year

Example: 2024

min_quantityintegerOptional

Minimum certificate quantity (in Wh)

Example: 1000000

limitinteger · min: 1 · max: 1000Optional

Maximum number of listings to return

Default: 100Example: 50

Responses

200

List of marketplace certificate listings

application/json

certificate_idintegerRequiredExample: 67890

issuance_idstringRequiredExample: WIND-2024-000001

account_idintegerRequiredExample: 2

quantityintegerRequired

Certificate quantity in Wh (1 MWh = 1,000,000 Wh)

Example: 1000000

energy_sourcestringRequiredExample: wind

vintage_yearintegerRequired

Year of energy production

Example: 2024

production_period_startstring · date-timeRequiredExample: 2024-01-01T00:00:00Z

production_period_endstring · date-timeRequiredExample: 2024-01-01T01:00:00Z

country_of_issuancestringRequiredExample: USA

project_namestring · nullableOptionalExample: Demo Wind Farm - Turbine Array

technology_typestring · nullableOptionalExample: wind_turbine

capacityinteger · nullableOptional

Device capacity in watts

Example: 100000

locationstring · nullableOptionalExample: Austin, TX

is_storagebooleanRequiredExample: false

expiry_datestring · date-timeRequiredExample: 2026-01-01T11:17:00Z

401

Authentication failed - invalid or missing API key

application/json

403

Access denied - insufficient permissions or account access

application/json

get

/external/marketplace/certificates

HTTPcURLJavaScriptPython

GET /api/external/marketplace/certificates HTTP/1.1
Host: dev.granularregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "certificate_id": 67890,
    "issuance_id": "WIND-2024-000001",
    "account_id": 2,
    "quantity": 1000000,
    "energy_source": "wind",
    "vintage_year": 2024,
    "production_period_start": "2024-01-01T00:00:00Z",
    "production_period_end": "2024-01-01T01:00:00Z",
    "country_of_issuance": "USA",
    "project_name": "Demo Wind Farm - Turbine Array",
    "technology_type": "wind_turbine",
    "capacity": 100000,
    "location": "Austin, TX",
    "is_storage": false,
    "expiry_date": "2026-01-01T11:17:00Z"
  }
]

Get Certificate Aggregates by Hour

get

https://dev.granularregistry.com/apihttp://localhost:8000

/external/accounts/{account_id}/certificate-aggregates

Get aggregated certificate data by hour for efficient marketplace operations. Returns total energy and certificate IDs for each hour period.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication using Bearer token format. Example: Authorization: Bearer gcreg_2fCeA78CA62644eB55B0A36249245A27

Path parameters

account_idintegerRequired

Account ID to query

Example: 1

Query parameters

vintage_startstring · date-timeOptional

Start of vintage period (ISO 8601 format)

Example: 2025-03-31T00:00:00Z

vintage_endstring · date-timeOptional

End of vintage period (ISO 8601 format)

Example: 2025-04-01T00:00:00Z

energy_sourcestring · enumOptional

Filter by energy source

Example: windPossible values:

statusstring · enumOptional

Filter by certificate status

Default: ACTIVEExample: ACTIVEPossible values:

device_idintegerOptional

Filter by device ID

Example: 1

limitinteger · min: 1 · max: 1000Optional

Maximum number of aggregated records to return

Default: 100Example: 24

offsetintegerOptional

Number of records to skip for pagination

Default: 0Example: 0

include_certificate_idsbooleanOptional

Whether to include certificate IDs in response (reduces response size if false)

Default: trueExample: true

Responses

200

Hourly aggregated certificate data

application/json

account_idintegerRequired

Account ID that was queried

Example: 1

account_namestringRequired

Name of the account

Example: Rattlesnake Wind Account

401

Authentication failed - invalid or missing API key

application/json

403

Access denied - insufficient permissions or account access

application/json

404

Resource not found

application/json

422

Invalid date range or parameters

application/json

get

/external/accounts/{account_id}/certificate-aggregates

HTTPcURLJavaScriptPython

GET /api/external/accounts/{account_id}/certificate-aggregates HTTP/1.1
Host: dev.granularregistry.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "account_id": 1,
  "account_name": "Rattlesnake Wind Account",
  "vintage_period": {
    "start": "2025-03-31T00:00:00Z",
    "end": "2025-04-01T00:00:00Z"
  },
  "aggregates": [
    {
      "hour": "2025-03-31T23:00:00Z",
      "energy_source": "wind",
      "total_mwh": 50,
      "certificate_count": 50,
      "certificate_ids": [
        "01K15XSS23Q88V5BB4S2922NAF",
        "01K15XSS23Z1R1NG90K0WZVKN0"
      ],
      "device_id": 1,
      "device_name": "Rattlesnake Wind - Turbine Array",
      "device_location": "Rattlesnake Wind Farm, TX",
      "country_of_issuance": "US",
      "issuing_body": "Texas Renewable Energy Commission"
    }
  ],
  "summary": {
    "total_hours": 24,
    "total_mwh": 1200.5,
    "total_certificates": 1200,
    "energy_sources": [
      "wind"
    ],
    "devices": [
      1
    ]
  }
}