Verdantix API Reference

Verdantix API v1

A RESTful API for integrating sustainable energy monitoring, carbon tracking, and smart grid optimization into your applications. Access real-time production data, automate ESG reporting, and deploy AI-driven efficiency recommendations.

Base URL All API requests must be made to:

https://api.verdantix.com/v1

The API uses standard HTTP methods and returns JSON payloads. All timestamps are in ISO 8601 format (UTC). Pagination uses cursor-based navigation for high-volume energy datasets.

Authentication

Verdantix uses API keys and Bearer tokens for authentication. Include your token in the Authorization header with every request.

Authorization: Bearer vr_live_sk_8f7d92j3k1m5n6p4

Security Best Practices Never expose your secret key in client-side code. Use environment variables and restrict key permissions to specific scopes (e.g., energy:read, carbon:write).

Rate Limits

API access is throttled to ensure fair usage and system stability. Current limits:

Standard Tier: 100 requests/minute, 1,000 requests/hour
Enterprise Tier: 1,000 requests/minute, custom hourly limits
Burst Limit: 20 concurrent webhooks per organization

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1698765432

API Endpoints

Click on any endpoint to view parameters, request examples, and response structures.

GET /energy/meters/{meter_id}/readings Retrieve historical & real-time energy production data

Parameters

Name	Type	Description
meter_id	string	Required. Unique identifier for the energy meter.
start_date	string	Optional. ISO 8601 timestamp. Defaults to 24h ago.
end_date	string	Optional. ISO 8601 timestamp. Defaults to now.
granularity	enum	`minute`, `hour`, `day` (default: `hour`)

Response Example

{
  "data": [
    { "timestamp": "2024-01-15T10:00:00Z", "kwh_produced": 12.4, "efficiency": 0.87 },
    { "timestamp": "2024-01-15T11:00:00Z", "kwh_produced": 14.1, "efficiency": 0.91 }
  ],
  "meta": { "cursor": "eyJpZCI6MTIzfQ==", "has_more": true }
}

POST /carbon/emissions Log and categorize carbon footprint data

Request Body

Field	Type	Description
source	string	Required. Emission source (e.g., `transport`, `manufacturing`)
co2_kg	number	Required. CO₂ equivalent in kilograms.
location	object	Optional. Geo coordinates for regional factor calculation.
metadata	object	Optional. Custom key-value pairs.

Response Example

{
  "id": "em_9x7z2k4m1p",
  "status": "recorded",
  "co2_kg": 45.2,
  "offset_available": true,
  "created_at": "2024-01-15T14:30:00Z"
}

GET /smart-grid/status Check real-time microgrid health & load balancing

Parameters

Name	Type	Description
grid_id	string	Required. Target microgrid identifier.
include_forecast	boolean	Optional. Return 24h load prediction.

Response Example

{
  "grid_id": "mg_sfc_01",
  "status": "operational",
  "current_load_kw": 240.5,
  "renewable_share": 0.78,
  "nodes_online": 12,
  "forecast": { "peak_demand_kw": 310, "expected_time": "2024-01-15T18:00:00Z" }
}

POST /optimization/recommend Generate AI-driven efficiency recommendations

Request Body

Field	Type	Description
facility_id	string	Required. Target facility identifier.
goals	array	Required. e.g., `["reduce_cost", "minimize_co2"]`
constraints	object	Optional. Budget caps, uptime requirements.

Response Example

{
  "recommendations": [
    {
      "action": "shift_load",
      "description": "Move HVAC cooling to 2AM-4AM window",
      "estimated_savings_usd": 1240,
      "co2_reduction_kg": 85
    }
  ],
  "confidence": 0.94
}

HTTP Status Codes

Verdantix uses standard HTTP status codes to indicate request outcomes.

200Success - Request processed

201Created - Resource added

204No Content - Deletion success

400Bad Request - Invalid parameters

401Unauthorized - Missing/invalid token

403Forbidden - Insufficient permissions

404Not Found - Resource missing

429Too Many Requests - Rate limited

500Server Error - Internal failure

Error Handling

Errors are returned as JSON with a consistent structure. Always check the error.code field for programmatic handling.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded 100 requests per minute.",
    "retry_after": 42,
    "documentation_url": "https://docs.verdantix.com/errors#rate_limit"
  }
}

SDKs & Tools

Official client libraries are available for popular languages. Community packages are also welcome.

Python: pip install verdantix-python
Node.js: npm install @verdantix/api
Go: go get github.com/verdantix/go-sdk

For SDK documentation, contribution guidelines, or Postman collections, visit the Developer Portal.