Emerging Platform API

How to call the Emerging Platform API: API keys from Mission Control, the bearer header, its endpoints, the error envelope, and the other IXO APIs.

This page covers the Emerging Platform API and the other IXO APIs that Emerging Platform integrations use. The Emerging Platform API lets a registry or another system read household, device, fuel, credit and claim data from the dMRV system. Solutions such as Emerging Household Energy consume it. Use this page to get a key, authenticate a request, find the endpoint you need and handle errors.

The contract for the Emerging Platform API is its OpenAPI description. Every endpoint page in the API reference is generated from it, and each one has a request console that sends a real request to the development server. Start with Get household statistics.

Endpoints

All endpoints are GET requests.

AreaEndpoints
HouseholdsHousehold statistics, stove stacking
DevicesDevice status and activity
FuelFuel usage
Carbon creditsIssued, cancelled, transferred, retired
ClaimsFuel purchase, fuel delivery, emission reduction, household onboarding

The credit endpoints report credits. The credits themselves are tokens, minted, transferred and retired with the token module: see Tokens. The claim endpoints report claims. A claim is decided by a decision oracle and the IXO decision engine, and Trust boundaries explains what a decision proves.

API keys

  • Every request needs an API key.
  • Keys are managed through Mission Control.
  • Access is capability-based.
  • Keys are specific to an environment.

Send the key as a bearer token in every request:

Authorization: Bearer YOUR_API_KEY

Security requirements:

  • TLS encryption is required.
  • Key rotation policies apply.
  • Rate limiting is enforced.
  • Requests are logged.

Errors

Branch on the HTTP status code. The error body of the Emerging Platform API guarantees only a message field, which is human-readable text and not a stable identifier. The OpenAPI description defines it, and Errors covers error handling across the API reference.

Other service hosts

The hosts below are named for Emerging Platform services. They are not described by the Emerging Platform API's OpenAPI contract. Check Status and Networks and endpoints before you rely on one.

GroupServiceHost
Impact Hub NetworkRegistryhttps://registry.emerging.eco/v1
Impact Hub NetworkClaimshttps://claims.emerging.eco/v1
Impact Hub NetworkVerificationhttps://verify.emerging.eco/v1
Data servicesMatrixhttps://matrix.emerging.eco/v1
Data servicesStoragehttps://storage.emerging.eco/v1
Data servicesQueryhttps://query.emerging.eco/v1
Oracle servicesAI verificationhttps://oracles.emerging.eco/v1
Oracle servicesAnalyticshttps://analytics.emerging.eco/v1

The response format below was documented for these hosts. It is an illustrative example. It is not the Emerging Platform API's error envelope, which is described under Errors.

Success response (illustrative example)
{
  "success": true,
  "data": {
    // Response data
  }
}
Error response (illustrative example)
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Other IXO APIs

APIWhat it does
Impact HubBlockchain APIs for registry and verification services
BlocksyncQueries indexed blockchain data with GraphQL
Data MatrixA Matrix server interface to private data rooms
Registry APIRegister and manage digital twins
VerificationProcess and validate claims
Data APIStore and retrieve data securely
Oracle APIAccess AI services

Integrate

  1. Get API credentials.
  2. Choose service endpoints.
  3. Implement authentication.
  4. Handle responses.

Throttle your requests to stay within the rate limit, handle errors, follow the security requirements above, and track your API usage and performance.

Developer tools