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

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

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

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

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

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
    ]
  }
}