AmpVerve API
APIs for distributed energy operations. Sites, assets, telemetry, recommendations, dispatch and verified receipts, exposed through a consistent REST interface. Public documentation is intentionally high-level; production access is scoped under NDA with least-privilege credentials.
Quickstart
Five steps from credentials to your first verified receipt.
Authentication
OAuth 2.0 client-credentials. All requests use a short-lived bearer token (60-minute TTL). Tokens are issued per-tenant and scoped to least-privilege roles.
Environments
| Environment | Base URL | Purpose |
|---|---|---|
| Production | https://api.ampverve.com/v1 | Live tenants, real assets, real dispatch |
| Sandbox | https://sandbox.ampverve.com/v1 | Synthetic telemetry, shadow recommendations, no dispatch |
| Staging | https://staging.ampverve.com/v1 | Pre-production, mirrors prod schema, restricted access |
Versioning
URL-versioned (/v1). Breaking changes ship under a new major version with a 12-month deprecation window. Additive changes (new fields, new endpoints) ship in-band without a version bump.
| Version | Status | Released | End-of-life |
|---|---|---|---|
v1 | GA | 2026 Q1 | - |
v2 | Beta | 2026 Q4 (planned) | - |
Sites
A site is the smallest billable unit in AmpVerve. Each site has a connection envelope, tariff context, market eligibility, and a list of assets behind the meter.
| Endpoint | Description |
|---|---|
GET /v1/sites GET | List sites your tenant can read |
GET /v1/sites/{id} GET | Single site with full envelope |
GET /v1/sites/{id}/capacity-model GET | Import / export limits, fuse limits, tariff context |
GET /v1/sites/{id}/market-eligibility GET | Active flex markets and route status |
Assets & telemetry
Assets cover EVs, AC and DC chargers, batteries, solar inverters, heat pumps, BMS, UPS systems and flexible loads. Telemetry is captured at 1-15 second resolution through supported adapters and aggregated to 1-minute, 30-minute and hourly grain.
| Endpoint | Description |
|---|---|
GET /v1/sites/{id}/assets GET | List assets at a site |
GET /v1/assets/{id}/telemetry?from=...&to=... GET | Time-series telemetry, granular |
GET /v1/assets/{id}/health GET | Battery SoH, charger uptime, alarms |
Supported adapter protocols
OCPP 1.6 / 2.0.1 · ISO 15118-2 / 20 · IEC 61850 · IEEE 2030.5 · OpenADR 3 · Modbus TCP · BACnet IP · DNP3 · SunSpec · 30+ proprietary vendor APIs (Indra, Wallbox, Tesla, MG iSmart, Daikin, Octopus, etc.)
Recommendations
Read-only optimisation output. Returns proposed setpoints, charge/discharge schedules and safety vetoes for an asset over a time horizon. Used in shadow mode before dispatch is enabled.
| Endpoint | Description |
|---|---|
GET /v1/sites/{id}/recommendations GET | Per-site recommendations |
GET /v1/sites/{id}/safety-events GET | Vetoed actions, with reasons |
GET /v1/sites/{id}/value-stack GET | Modelled revenue stack by route |
Dispatch
Approved control instructions. Dispatch endpoints require an additional scope and are gated by per-tenant safety rules. All instructions are signed and logged.
| Endpoint | Description |
|---|---|
POST /v1/dispatch/events POST | Submit a dispatch instruction |
GET /v1/dispatch/events/{id} GET | Status of a dispatch instruction |
POST /v1/dispatch/{id}/abort POST | Cancel an in-flight dispatch |
Receipts
Cryptographically signed records of every dispatch decision and verified outcome. Receipts support PDF, JSON and JSON-LD output for settlement, audit and ESG reporting.
| Endpoint | Description |
|---|---|
POST /v1/receipts/export POST | Export verified receipts for a period |
GET /v1/receipts/{id} GET | Single receipt |
GET /v1/receipts/{id}/verify GET | Cryptographic verification of receipt |
Webhooks
Event-driven notifications for dispatch, safety, settlement and asset health. Signed with HMAC-SHA256 over a per-tenant secret.
| Event | Description |
|---|---|
dispatch.executed | Dispatch instruction completed on hardware |
dispatch.vetoed | Safety agent blocked an instruction |
asset.alarm.raised | Asset reported a fault or constraint breach |
receipt.issued | Verified receipt created and ready to export |
market.window.opened | Flex market accepting bids for the next interval |
Rate limits
Per-tenant token bucket. Standard limits below; enterprise tenants negotiate higher caps under contract.
| Tier | Reads / minute | Writes / minute | Webhook delivery |
|---|---|---|---|
| Sandbox | 60 | 20 | 10 / minute |
| Standard | 600 | 200 | 100 / minute |
| Enterprise | Negotiated | Negotiated | Negotiated |
Errors
Standard HTTP status codes. Error responses include a stable code, a human-readable message, and a per-request trace_id for support.
Status
Subscribe to incident notifications at status.ampverve.com. SLA: 99.9% for control-plane reads, 99.95% for dispatch endpoints.
SDKs & client libraries
ampverve-python
pip install ampverve · async client, type hints, retries built in. GA
@ampverve/sdk
npm install @ampverve/sdk · fetch-based, tree-shakable. GA
ampverve-java
Maven Central. JDK 17+. Beta
ampverve-go
go get github.com/ampverve/ampverve-go · context-aware. Beta
Changelog
/v1/sites/{id}/capacity-model.market.window.opened event for flex-market scheduling.Talk to engineering
Integration support, schema clarifications, sandbox provisioning and architectural advice.