Energy Infrastructure API

The Aevum Zenth Energy Infrastructure API provides programmatic access to real-time grid telemetry, fusion plant diagnostics, smart meter aggregations, and cross-regional energy distribution routing. Built for enterprise integrations, grid operators, and third-party clean-tech developers.

Base URL

HTTPS

https://api.aevumzenth.com/energy/v2

All requests must use HTTPS. Unencrypted connections will return 403 Forbidden.

Authentication

Access to the Energy Infrastructure API requires a valid API key issued by the Aevum Zenth Developer Portal. All requests must include the key in the Authorization header using Bearer scheme.

Example

Authorization: Bearer AZ_EK_8f9a2b3c4d5e6f7g8h9i0j1k2l3m4n5o

API keys are scoped to specific divisions (Energy, Grid Ops, Fusion R&D). Ensure your key includes the energy.infra.* permission set. Keys expire after 24 months and must be rotated via the dashboard.

Rate Limits

Requests are limited per API key to ensure grid system stability and fair usage. Limits vary by tier and endpoint criticality.

Tier	Grid/Telemetry	Smart Meters	Webhooks
Developer	120 / min	60 / min	50 / min
Enterprise	1,200 / min	600 / min	500 / min
Grid Partner	5,000 / min	2,400 / min	2,000 / min

Exceeding limits returns 429 Too Many Requests. The response includes a Retry-After header in seconds.

Grid Status & Load

GET /grid/status/{region_id} Regional Grid Telemetry

Retrieves real-time voltage, frequency, load capacity, and stability metrics for a designated macro-region.

Path Parameters

Parameter	Type	Description
`region_id`REQUIRED	string	ISO 3166-2 region code or Aevum internal zone ID (e.g., `EU-WEST-3`)

Response `200 OK`

JSON
{
  "region": "EU-WEST-3",
  "timestamp": "2026-01-15T08:30:00Z",
  "status": "stable",
  "metrics": {
    "voltage_avg": 230.4,
    "frequency": 50.02,
    "load_capacity_pct": 78.5,
    "renewable_mix": 0.84,
    "grid_inertia": "high"
  },
  "alerts": []
}

Energy Distribution

POST /distribution/route Dynamic Load Routing

Submits a routing request for surplus energy redistribution across interconnected zones. Returns an optimization plan with estimated latency and loss factors.

Request Body

JSON
{
  "source_zone": "AF-SOUTH-1",
  "target_zones": ["AF-SOUTH-2", "EU-SOUTH-4"],
  "capacity_mw": 450,
  "priority": "critical",
  "max_loss_tolerance": 0.04
}

Response `202 Accepted`

JSON
{
  "request_id": "req_9x8c7v6b5n4m",
  "status": "processing",
  "estimated_completion": "2026-01-15T08:32:15Z",
  "routing_plan": {
    "path": ["AF-SOUTH-1", "NODE-77", "EU-SOUTH-4"],
    "efficiency": 0.96,
    "latency_ms": 142
  }
}

Plant Telemetry (Fusion & Renewables)

GET /telemetry/plant/{plant_id} Facility Diagnostics

Streams aggregated telemetry from Aevum Zenth fusion reactors, hydroelectric arrays, and solar microgrids. Requires energy.tier2 clearance.

Query Parameters

Parameter	Type	Description
`window`	string	Time window: `1h`, `24h`, `7d` (default: `1h`)
`metrics`	array	Comma-separated: `core_temp,neutron_flux,coolant_flow,turbine_rpm`

Response `200 OK`

JSON
{
  "plant_id": "FUSION-ALPHA-01",
  "type": "tokamak_fusion",
  "readings": [
    { "ts": "2026-01-15T08:30:00Z", "core_temp_k": 150000000, "neutron_flux": 4.2e14, "output_mw": 1200 },
    { "ts": "2026-01-15T08:30:30Z", "core_temp_k": 150000000, "neutron_flux": 4.1e14, "output_mw": 1198 }
  ]
}

Error Handling

The API uses standard HTTP status codes. Error responses include a machine-readable error_code and human-readable message.

Code	Meaning	Details
`400`	Bad Request	Invalid JSON, missing parameters, or malformed query
`401`	Unauthorized	Missing or expired API key
`403`	Forbidden	Insufficient permissions for requested resource
`404`	Not Found	Resource or endpoint does not exist
`429`	Rate Limited	Exceeded request quota. Check `X-RateLimit-Reset`
`503`	Service Unavailable	Grid maintenance or upstream fusion array offline

Example Error Response
{
  "error": "insufficient_clearance",
  "message": "Access denied. Requires energy.tier2 or higher clearance level.",
  "trace_id": "az_trace_8f7g6h5j4k3l2"
}

SDKs & Libraries

Official SDKs are available for Python, Go, and Rust. Community-maintained wrappers exist for Node.js, Java, and C#.

Python (pip)

Terminal

pip install aevum-zenth-energy

Python

from aevum_zenth import EnergyAPI

client = EnergyAPI(api_key="AZ_EK_your_key_here")
grid_status = client.grid.get_status(region_id="NA-EAST-2")
print(grid_status.metrics.load_capacity_pct)

For Go, Rust, and other language bindings, visit the Developer Hub. All SDKs support async operations, automatic retries, and WebSocket streaming for real-time telemetry.

Energy Infrastructure API

Base URL

Authentication

Rate Limits

Grid Status & Load

Path Parameters

Response 200 OK

Energy Distribution

Request Body

Response 202 Accepted

Plant Telemetry (Fusion & Renewables)

Query Parameters

Response 200 OK

Error Handling

SDKs & Libraries

Python (pip)

Response `200 OK`

Response `202 Accepted`

Response `200 OK`