📖 Technical Documentation

Welcome to the Env API documentation. This reference covers authentication, endpoints, data models, and integration patterns for the Env sustainability platform.

Overview

The Env API exposes RESTful endpoints for tracking carbon emissions, synchronizing utility data, generating ESG compliance reports, and monitoring supply chain sustainability metrics. All requests and responses use JSON.

Request Format

{
  "organization_id": "org_9x8f7h6g5",
  "scope": [1, 2, 3],
  "period": "2024-Q3",
  "include_supply_chain": true
}

Response Format

{
  "status": "success",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit_remaining": 482
  }
}

Authentication

Authenticate using Bearer tokens. Include your API key in the Authorization header. Keys can be generated from the Dashboard → API Settings.

Authorization: Bearer sk_env_prod_8x7d6f5e4c3b2a1z

Environment tokens have distinct prefixes:
sk_env_test_... for sandbox
sk_env_prod_... for production

Base URL

https://api.env.tech/v1

Carbon Metrics

GET /carbon/metrics

Retrieves aggregated carbon footprint data for the authenticated organization.

Query Parameters

Example Request

curl -X GET "https://api.env.tech/v1/carbon/metrics?scope=all&start_date=2024-01-01&end_date=2024-06-30" \
  -H "Authorization: Bearer sk_env_prod_8x7d6f5e4c3b2a1z"

Energy Data

POST /energy/sync

Pushes raw utility meter readings. Env normalizes units, applies grid emission factors, and calculates CO₂e automatically.

Request Body

{
  "meter_id": "meter_ny_4492",
  "readings": [
    { "timestamp": "2024-08-15T00:00:00Z", "kwh": 12450 },
    { "timestamp": "2024-08-16T00:00:00Z", "kwh": 11980 }
  ],
  "source": "smart_meter_api"
}

Compliance Reports

GET /compliance/reports

Generates downloadable ESG reports aligned with GRI, SASB, and TCFD standards.

Response Codes

Supply Chain

GET /supply-chain/risks

Returns environmental risk scores for tier-1 and tier-2 suppliers. Uses satellite imagery, news sentiment, and historical compliance data.

SDKs & Libraries

Official client libraries are available for major languages. Community-maintained packages are also supported.

# Python
pip install env-sdk

# Node.js
npm install @env/api-client

# Go
go get github.com/env-tech/go-sdk

Initialization

import env

client = env.Client(api_key="sk_env_prod_...")
metrics = client.carbon.get(scope="all")

Webhooks

Subscribe to real-time events by registering a webhook endpoint in your dashboard. Env retries failed deliveries with exponential backoff (up to 48 hours).

Event Types

• carbon.threshold_exceeded — Emissions surpass configured limits
• compliance.report_ready — ESG report generation complete
• supply_chain.risk_alert — Supplier sustainability score drops below threshold

Signature Verification

All webhooks include an X-Env-Signature header. Verify using HMAC-SHA256 with your webhook secret.

def verify(payload, signature, secret):
    digest = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", signature)

Error Handling

Env uses standard HTTP status codes. Error responses include a machine-readable code and human-readable message.

{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field 'scope' must be one of: 1, 2, all",
    "details": { "field": "scope", "value": "4" }
  }
}

Rate Limits

API rate limits are applied per API key. Headers indicate current usage.