API Documentation

Welcome to the Verdantix API. Our RESTful API allows you to integrate renewable energy monitoring, carbon footprint tracking, and smart grid optimization directly into your applications. All requests and responses use JSON format.

HTTP

GET https://api.verdantix.com/v1/energy-metrics
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Base URL

All API requests should be made to:

URL

https://api.verdantix.com/v1

Authentication

The Verdantix API uses Bearer Token authentication. Include your API key in the Authorization header for every request. Generate your key from the Developer Dashboard.

Header

Authorization: Bearer sk_live_51Mz8f9xK2Lp4nQ7vR3sT6uY8wA2bC4dE5fG6hH7iJ8kL9mN0oP1qR2sT3uV4wX5yZ6

Environment Note: Use sk_test_ prefixes for sandbox/testing environments.

Endpoints

Below are the core endpoints for interacting with the Verdantix green tech ecosystem.

GET /energy-metrics

Retrieve real-time and historical energy generation/consumption data across your registered assets.

Parameter	Type	Required	Description
`facility_id`	string	Yes	UUID of the facility
`start_date`	ISO 8601	No	Query start time
`end_date`	ISO 8601	No	Query end time

JSON

{
  "data: {
    "facility_id: "fac_8x7y6z5w4v3u2t1s0r9q8p7o6n5m4l3k2j1i0h",
    "total_generation_kwh: 4582.3,
    "total_consumption_kwh: 3891.5,
    "net_carbon_offset_kg: 1240.7,
    "timestamp: "2025-06-15T14:32:00Z"
  }
}

POST /carbon-reports

Submit carbon footprint data for automatic verification, aggregation, and ESG compliance reporting.

JSON

{
  "facility_id: "fac_8x7y6z5w4v3u2t1s0r9q8p7o6n5m4l3k2j1i0h",
  "scope: "scope_1",
  "emissions_co2e_kg: 15200,
  "measurement_period: {
    "start: "2025-01-01",
    "end: "2025-03-31"
  },
  "methodology: "GHG-Protocol"
}

JSON

{
  "id: "crp_9a8b7c6d5e4f3g2h1i0j",
  "status: "verified",
  "created_at: "2025-04-01T09:15:00Z",
  "verification_token: "vt_2x3y4z5a6b7c8d9e0f1g"
}

GET /facilities/{id}

Fetch detailed configuration, installed green tech assets, and operational status for a specific facility.

JSON

{
  "id: "fac_8x7y6z5w4v3u2t1s0r9q8p7o6n5m4l3k2j1i0h",
  "name: "West Coast Solar Hub",
  "status: "active",
  "assets: [
    { "type: "solar_array, "capacity_kw: 500 },
    { "type: "battery_storage, "capacity_kwh: 1200 }
  ],
  "grid_connection: "microgrid_hybrid"
}

PUT /smart-grid/{id}/optimize

Trigger AI-driven optimization for load balancing, storage discharge scheduling, and renewable integration.

JSON

{
  "priority: "cost_reduction",
  "target_load_reduction: 0.15,
  "respect_peak_hours: true
}

JSON

{
  "job_id: "opt_1a2b3c4d5e6f7g8h9i0j",
  "status: "processing",
  "estimated_completion: "2025-06-15T14:45:00Z",
  "webhook_url: "https://api.verdantix.com/v1/webhooks/opt_1a2b3c4d5e6f7g8h9i0j"
}

Error Handling

The Verdantix API uses standard HTTP status codes and returns detailed error objects when requests fail.

Code	Meaning	Description
`400`	Bad Request	Invalid parameters or malformed JSON
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for requested resource
`404`	Not Found	Endpoint or resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected error on our end

Error Response

{
  "error: {
    "code: "invalid_api_key",
    "message: "The provided API key is expired or malformed.",
    "status: 401,
    "request_id: "req_9x8y7z6w5v4u3t2s1r0q"
  }
}

Rate Limits

API requests are limited to ensure fair usage and system stability. Limits are applied per API key.

Standard Plan: 1,000 requests / hour
Enterprise Plan: 10,000 requests / hour
Webhooks: 100 / minute

Rate limit information is included in response headers:

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1718459400

SDKs & Tools

Official client libraries are available for popular languages. Community maintained SDKs are also listed on our GitHub repository.

Python JavaScript Go Rust