Verdantix API Documentation

Integrate real-time energy monitoring, carbon tracking, and renewable asset management directly into your applications. Our RESTful API is designed for scalability, security, and sustainability.

Production Ready SOC 2 Type II Base URL: https://api.verdantix.com/v2

Authentication

All API requests require authentication via API Key. Include your key in the Authorization header using the Bearer scheme.

Keep your API keys secure. Never expose them in client-side code or public repositories. Rotate keys every 90 days.

HTTP Header

Authorization: Bearer vnd_live_sk_8f7a9c2e1d4b6...

API keys can be generated and managed in your Dashboard > API Keys section. Separate keys are available for sandbox and production environments.

Core Endpoints

GET /sites/{site_id}/energy-readings

Retrieve historical and real-time energy consumption data for a specific site, including solar, wind, and grid inputs.

Parameter	Type	Description
site_id*	string	Unique identifier for the monitored facility
start_date	ISO 8601	Start of the query window
end_date	ISO 8601	End of the query window
resolution	enum	Granularity: `hourly`, `daily`, `monthly`

Example Response (200 OK)

{
  "data": [
    {"timestamp": "2025-08-12T10:00:00Z", "solar_kw": 45.2, "grid_kw": 12.1, "storage_kw": -5.0},
    {"timestamp": "2025-08-12T11:00:00Z", "solar_kw": 62.8, "grid_kw": 0.0, "storage_kw": 8.3}
  ],
  "pagination": {"next_cursor": "eyJpZCI6MTIzfQ==", "has_more": true}
}

POST /carbon-footprint/calculate

Submit operational data to generate a Scope 1 & 2 carbon footprint report using ISO 14064 compliant methodologies.

Parameter	Type	Description
energy_kwh*	number	Total energy consumption in kWh
grid_region	string	ISO 3166-2 region code for emission factors
renewable_percentage	number	Portion of energy from verified green sources (0-100)

Example Response (201 Created)

{
  "report_id": "rpt_9x8k2m4p",
  "scope_2_mt_co2e": 142.5,
  "scope_1_mt_co2e": 0,
  "neutralized_mt_co2e": 35.6,
  "offset_credits_recommended": 106.9,
  "generated_at": "2025-08-12T14:30:00Z"
}

PUT /devices/{device_id}/config

Remotely update configuration parameters for Verdantix IoT metering devices. Changes apply within 60 seconds.

This endpoint requires admin:devices scope. Improper configuration may interrupt data collection.

Rate Limiting & Pagination

API requests are limited to 1,000 requests per minute per API key. Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1723489200
Retry-After: 45

Pagination uses cursor-based navigation. Always follow the next_cursor in the response payload to retrieve subsequent pages. Results are capped at 100 items per request.

Error Handling

The API uses standard HTTP status codes. Detailed error objects are returned in the response body:

Code	Meaning	Resolution
400	Bad Request	Check payload structure and required parameters
401	Unauthorized	Verify API key validity and environment match
403	Forbidden	Key lacks required scopes or role permissions
429	Too Many Requests	Implement exponential backoff per Retry-After header
500	Internal Error	Service temporarily degraded; contact support if persistent

Error Response Format

{
  "error": {
    "code": "invalid_payload",
    "message": "Field 'grid_region' must be a valid ISO 3166-2 code",
    "details": {"field": "grid_region", "value": "XX-INVALID"},
    "request_id": "req_88f2a9c1"
  }
}

SDKs & Code Examples

We provide official SDKs for Python, Node.js, Go, and Ruby. Install via package managers:

Python / pip

pip install verdantix-sdk

Usage Example

from verdantix import Client

client = Client(api_key="vnd_live_sk_...")
readings = client.sites.get_readings(
    site_id="site_abc123",
    resolution="daily",
    start_date="2025-07-01"
)

for r in readings:
    print(f"{r.timestamp}: {r.solar_kw} kW solar")

Full SDK documentation, webhook setup guides, and Postman collections are available in the Developer Hub.

Developer Support

Need help integrating? Our engineering team monitors developer channels and responds within 4 business hours.

Email: api-support@verdantix.com
Community: Verdantix Developer Discord
Changelog: API Version History

Found a bug or have a feature request? Submit it via our GitHub Issue Tracker with your request ID for faster resolution.