External API
External-facing endpoints for marketplace integration
Get high-level account statistics including certificate counts and project information
Account ID to query
1Account summary data
Authentication failed - invalid or missing API key
Access denied - insufficient permissions or account access
Resource not found
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 detailed certificate listings for a specific account with filtering options
Account ID to query
1Filter by certificate status
ACTIVEPossible values: Filter by device ID
1Maximum number of certificates to return
100Example: 10Number of certificates to skip
0Example: 0List of certificates
Authentication failed - invalid or missing API key
Access denied - insufficient permissions or account access
Resource not found
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 project (device) information for an account including certificate statistics
Account ID to query
1List of projects
Authentication failed - invalid or missing API key
Access denied - insufficient permissions or account access
Resource not found
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 certificates optimized for marketplace trading (requires TRADING_USER role or higher)
Filter by energy source
windPossible values: Filter by country of issuance
USAMinimum vintage year
2024Maximum vintage year
2024Minimum certificate quantity (in Wh)
1000000Maximum number of listings to return
100Example: 50List of marketplace certificate listings
Authentication failed - invalid or missing API key
Access denied - insufficient permissions or account access
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 aggregated certificate data by hour for efficient marketplace operations. Returns total energy and certificate IDs for each hour period.
Account ID to query
1Start of vintage period (ISO 8601 format)
2025-03-31T00:00:00ZEnd of vintage period (ISO 8601 format)
2025-04-01T00:00:00ZFilter by energy source
windPossible values: Filter by certificate status
ACTIVEExample: ACTIVEPossible values: Filter by device ID
1Maximum number of aggregated records to return
100Example: 24Number of records to skip for pagination
0Example: 0Whether to include certificate IDs in response (reduces response size if false)
trueExample: trueHourly aggregated certificate data
Authentication failed - invalid or missing API key
Access denied - insufficient permissions or account access
Resource not found
Invalid date range or parameters
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
]
}
}Was this helpful?