API Overview

The Verdantix REST API provides programmatic access to your sustainability data, energy metrics, and installation management. Use it to integrate green tech analytics into your applications, automate reporting, and build custom dashboards.

Base URL: https://api.verdantix.com/v1

Note: All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Quick Example

cURL

# Fetch latest energy metrics for your account
curl -X GET "https://api.verdantix.com/v1/energy-metrics" \
  -H "Authorization: Bearer $VERDANTIX_API_KEY" \
  -H "Content-Type: application/json"

Authentication

Verdantix uses Bearer Token authentication to authorize API requests. You can generate and manage API keys from your dashboard settings.

Include your API key in the Authorization header of every request:

Header

Authorization: Bearer <your_api_key>

Security: Never expose your API keys in client-side code or public repositories. Use environment variables or secure secret management systems.

Energy Metrics

GET /v1/energy-metrics

Retrieve real-time and historical energy generation and consumption data for your installations.

Query Parameters

Parameter	Type	Description
`installation_id`	string	Optional. Filter by specific installation.
`start_date`	string	Optional. ISO 8601 date format.
`end_date`	string	Optional. ISO 8601 date format.
`interval`	string	Optional. `hour`, `day`, or `month`.

Response

                            JSON
                            
                        
{
  "status": "success",
  "data": {
    "total_generation_kwh": 4528.32,
    "total_consumption_kwh": 3102.15,
    "net_savings_usd": 682.40,
    "renewable_percentage": 76.8,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Carbon Reports

POST /v1/carbon-reports

Generate a comprehensive carbon footprint report for a specified period. Reports are processed asynchronously and delivered via webhook.

Request Body

Field	Type	Required	Description
`scope`	string	Yes	Scope 1, 2, or 3. Comma-separated allowed.
`period_start`	string	Yes	ISO 8601 date.
`period_end`	string	Yes	ISO 8601 date.
`format`	string	No	Default: `json`. Options: `pdf`, `csv`.

                            JSON Body
                            
                        
{
  "scope": "1,2",
  "period_start": "2024-01-01",
  "period_end": "2024-12-31",
  "format": "pdf"
}

Installations

GET /v1/installations

List all solar, wind, and storage installations registered under your account.

POST /v1/installations

Register a new renewable energy installation.

DELETE /v1/installations/:id

Remove an installation from your account. This action cannot be undone.

Rate Limiting

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

Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1706000000

429 Too Many Requests: Returned when you exceed the rate limit. Implement exponential backoff in your retry logic.

Error Codes

Verdantix uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with details:

Code	Description
`400`	Bad Request - Invalid parameters or malformed JSON
`401`	Unauthorized - Missing or invalid API key
`403`	Forbidden - Insufficient permissions for requested action
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Error Response
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has expired.",
    "documentation_url": "https://docs.verdantix.com/errors/invalid_api_key"
  }
}

SDKs & Tools

Official client libraries are available to simplify integration. Community packages are also welcome.

Python: pip install verdantix-python
Node.js: npm install @verdantix/sdk
OpenAPI Spec: /openapi.json