Energy Management API Reference

Programmatic access to Verdantix's renewable energy monitoring, forecasting, and carbon offset infrastructure.

Base URL: https://api.verdantix.io/v2
All endpoints return JSON. Timestamps follow ISO 8601 format.

Authentication

All requests require a Bearer token in the Authorization header. Tokens can be generated in your Developer Dashboard.

Authorization Header

Authorization: Bearer sk_live_vx_7f8a9b2c3d4e5f6g7h8i9j0k

SDK Installation

Install the official Verdantix SDK for your preferred runtime:

NPM / Yarn

npm install @verdantix/energy-sdk
yarn add @verdantix/energy-sdk

Python (pip)

pip install verdantix-sdk

Core Endpoints

Interact with meters, forecasts, and carbon offsets using the following REST endpoints:

GET /meters List all active energy meters

POST /meters/{id}/readings Submit real-time telemetry

GET /forecasts/grid Retrieve 72h load & generation forecasts

POST /carbon/offsets Purchase & register verified offsets

Example: Submit Meter Reading

Send telemetry from an edge device or inverter gateway:

POST /meters/vx_m_7721/readings

curl -X POST https://api.verdantix.io/v2/meters/vx_m_7721/readings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2025-09-12T14:32:00Z",
    "kwh_generated": 42.8,
    "power_factor": 0.98,
    "inverter_temp_c": 41.2,
    "status": "operational"
  }'

Response Schema

Field	Type	Description
`id`	string	Unique reading identifier
`meter_id`	string	Associated meter UUID
`validated`	boolean	Whether the reading passed anomaly detection
`carbon_offset_tons`	number	Estimated CO₂ avoided based on grid mix

Rate Limiting: Meter telemetry endpoints are limited to 100 requests/minute per meter ID. Bulk uploads should use the /meters/batch endpoint instead.

Webhooks

Subscribe to real-time events for grid stability alerts, threshold breaches, and offset verifications:

Event Payload Example

{
  "event": "meter.threshold_exceeded",
  "data": {
    "meter_id": "vx_m_7721",
    "threshold": "voltage_surge",
    "value": 254.3,
    "limit": 250.0,
    "action_taken": "auto_shutdown"
  },
  "timestamp": "2025-09-12T15:01:22Z"
}

Error Handling

Verdantix uses conventional HTTP status codes:

Code	Meaning	Common Cause
`400`	Bad Request	Invalid JSON schema or missing required fields
`401`	Unauthorized	Missing or expired API key
`403`	Forbidden	Token lacks scope for requested resource
`429`	Too Many Requests	Exceeded rate limit. Retry after `Retry-After` header
`503`	Service Unavailable	Grid data pipeline maintenance