Status labels are part of the contract

Every operation carries a label, recorded in the specification as x-ampverve-status. Treat it as binding.

Figures that are not a direct reading carry a data basis, recorded as x-ampverve-data-basis, with a one sentence method:

Measured, stored and configured figures carry no badge. Do not use a calculated or forecast figure for settlement or a financial claim unless the operation says so.

Market and region coverage

Where this API works today, stated by market and by region. Energy markets, tariffs and prices are Great Britain only. Getting device and telemetry data in is not tied to a country. Connecting a device somewhere does not open any market there.

Live in Great Britain

The market, tariff and price operations are built for GB: amounts are in GBP, periods are half hours, and local days are Europe/London days, clock change days included. Each operation's own label still applies.

A deployed GB route is not a market qualification. The GB market guide lists the gates that still apply per programme, asset and organisation.

Global today

These operations take data from devices and systems wherever they are. Timestamps are UTC with an explicit offset, units are canonical, and nothing in them assumes GB.

• Accounts are connected in the app. Connecting a vehicle or Home Assistant account, with its consent, happens in the AmpVerve app, and chargers are onboarded with AmpVerve. Those connection flows are not part of this API yet.
• Region fields. SLA policies and reports take any IANA timezone, and settlement receipts carry a currency. Most other money fields are GBP by name (_gbp), the Hub tariff policy's currency defaults to GBP, and its compliance checks are GB regulations.

Through partners

See the United States market guide for the route and its open gates.

Not available yet

• Energy markets outside GB. No market, flexibility, price or settlement operation exists for Europe, Ireland, Australia, New Zealand, Canada or any other market. The US is reachable only through the partner route above; no ISO or RTO, such as CAISO or ERCOT, is reached directly.
• Tariffs and prices outside GB. Tariff, price, charge stack and carbon intensity data are GB only.
• Capability discovery. Country, asset and market capability is agreed per organisation with AmpVerve; there is no discovery operation in the API. See Global capability discovery.

The country index and the market guides record the evidence for each market. A market moves into this page only when its operations are deployed and labelled in the specification.

Quickstart

From nothing to an authenticated read of your own organisation's data.

1. Confirm the platform is up

   No credential needed. This is also the endpoint to poll in production to detect degradation. The status page shows every public API component.

   curlCopy

   curl https://app.ampverve.com/api/telemetry/readyz

   ResponseCopy

   {
     "status": "ready",
     "checks": { "kafka": true, "redis": true, "database": true }
   }

2. Get a credential

   An organisation administrator creates an API key in the console under Settings, API access (app.ampverve.com/settings/api-access). Choose the scopes the integration needs. The key is shown once; store it in your secret manager.

   API keys read the Partner API operations only. Every other authenticated operation takes an access token. See Authentication for both.

3. Check the key

   GET /api/devtools/partner/v1/me needs no scope and tells you which organisation and key the request resolved to.

   curlPythonJavaScriptCopy

   curl https://app.ampverve.com/api/devtools/partner/v1/me \
     -H "Authorization: Bearer $AMPVERVE_API_KEY"

   import os
   import requests
   
   resp = requests.get(
       "https://app.ampverve.com/api/devtools/partner/v1/me",
       headers={"Authorization": f"Bearer {os.environ['AMPVERVE_API_KEY']}"},
       timeout=30,
   )
   resp.raise_for_status()
   print(resp.json())

   const resp = await fetch("https://app.ampverve.com/api/devtools/partner/v1/me", {
     headers: { Authorization: `Bearer ${process.env.AMPVERVE_API_KEY}` },
   });
   if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
   console.log(await resp.json());

   ResponseCopy

   {
     "organisation_id": "demo-partner",
     "key": {
       "id": "9b1e...",
       "prefix": "avk_3f9a1c2b7d4e",
       "name": "Partner production",
       "scopes": ["alerts:read"],
       "expires_at": "2027-01-01T00:00:00Z"
     }
   }

4. Read your data

   With the devices:read scope, list the devices registered to your organisation. A key without the scope gets 403 insufficient_scope.

   curlPythonJavaScriptCopy

   curl "https://app.ampverve.com/api/devtools/partner/v1/devices?limit=10" \
     -H "Authorization: Bearer $AMPVERVE_API_KEY"

   resp = requests.get(
       "https://app.ampverve.com/api/devtools/partner/v1/devices",
       headers={"Authorization": f"Bearer {os.environ['AMPVERVE_API_KEY']}"},
       params={"limit": 10},
       timeout=30,
   )
   resp.raise_for_status()
   for device in resp.json()["devices"]:
       print(device["id"], device["device_type"])

   const resp = await fetch("https://app.ampverve.com/api/devtools/partner/v1/devices?limit=10", {
     headers: { Authorization: `Bearer ${process.env.AMPVERVE_API_KEY}` },
   });
   const { devices } = await resp.json();

   Prefer Postman? Import the AmpVerve Postman collection, set its apiKey variable to your key, and run Developer tools, Partner API requests as they are. It is generated from the same specification, so it lists only what a key can call today.

   Next: subscribe to webhooks instead of polling, or follow the integration journey. To write telemetry, use an access token and read Getting data in first.

Authentication

Two credentials, both sent as Authorization: Bearer .... Which one an operation takes is shown on every operation in the reference.

A JWT sent to a Partner API operation is refused with 401, and an API key sent to any other operation is refused with 401. The organisation always comes from the credential. No header, parameter or body field can name a different one.

API keys Live

Key format

avk_<12 lowercase hex>_<43 base64url characters>. The first two parts, for example avk_3f9a1c2b7d4e, are the public prefix shown in lists and logs. The last part is the secret. AmpVerve stores only the prefix and an HMAC-SHA256 of the key under a server secret, so nobody, AmpVerve included, can show a key again after it is created.

Create a key

Organisation administrators (ORG_ADMIN) only. In the console open Settings, API access, choose a name, scopes and expiry, and copy the key from the one-time reveal. Or call POST /api/devtools/apikeys with an administrator's access token:

curl -X POST https://app.ampverve.com/api/devtools/apikeys \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Partner production","scopes":["alerts:read","devices:read"],"expires_in_days":90}'

{
  "api_key": {
    "id": "9b1e...",
    "name": "Partner production",
    "prefix": "avk_3f9a1c2b7d4e",
    "scopes": ["alerts:read", "devices:read"],
    "status": "active",
    "rate_limit_per_minute": 600,
    "expires_at": "2027-01-03T10:00:00Z"
  },
  "key": "avk_3f9a1c2b7d4e_Zr0...43 characters",
  "warning": "..."
}

Scopes

Every key needs at least one scope. Scopes are read only.

Expiry, limits, rotation and revocation

• Expiry is required: 1 to 365 days, default 90. An expired key gets 401 API key expired.
• At most 25 active keys per organisation, and each key is limited to 600 requests a minute.
• Rotate with POST /api/devtools/apikeys/{key_id}/rotate. The new key keeps the name, scopes and rate limit and is shown once. The old key stops working immediately, or after grace_period_hours (at most 72) so you can deploy the new one first.
• Revoke with POST /api/devtools/apikeys/{key_id}/revoke, or in Settings, API access. Requests with the key are refused with 401 from that moment.

What a refusal looks like

// error.code is one of api_key_missing, api_key_invalid, api_key_revoked,
// api_key_expired or api_key_required (a credential that is not an API key)
{
  "detail": "API key expired",
  "error": { "code": "api_key_expired", "message": "API key expired", "request_id": "req_4be1..." }
}

// the key is valid but lacks the scope this operation needs
{
  "detail": { "error": "insufficient_scope", "required_scope": "devices:read" },
  "error": { "code": "insufficient_scope", "message": "This API key does not hold the scope devices:read", "request_id": "req_4be1..." }
}

// with Retry-After and RateLimit-* headers, in seconds
{
  "detail": "Rate limit exceeded for this API key",
  "error": { "code": "rate_limited", "message": "Rate limit exceeded for this API key", "request_id": "req_4be1..." }
}

If key authentication is not configured on the service, every key is refused with 503. The control fails closed; it never falls back to another credential.

Access tokens

Every authenticated operation outside the Partner API takes an access token. Use a dedicated integration user in your organisation; never share a person's interactive login with a service.

curl -X POST https://app.ampverve.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"integration@example.com","password":"<your password>"}'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

# the refresh token you send is revoked; store the new pair
curl -X POST https://app.ampverve.com/api/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh_token>"}'

curl -X POST https://app.ampverve.com/api/auth/logout \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh_token>"}'

Cache the access token and refresh it at about 80 percent of its lifetime. Treat a 401 as a signal to refresh once and retry once; a retry loop runs into the authentication limit.

Roles, not scopes

Access tokens carry roles: ORG_ADMIN, OPERATOR, ANALYST, RESEARCHER and VIEWER. Each operation's description states the roles it needs where it restricts them. Ingestion needs ORG_ADMIN, OPERATOR or ANALYST; API key and webhook management needs ORG_ADMIN. A role that does not satisfy an operation gets 403 Insufficient permissions, and an X-Tenant-ID header that disagrees with the token gets 403 Tenant mismatch.

Single sign-on Live

Organisations that sign in with Microsoft Entra ID can exchange an Entra ID token for an AmpVerve session at POST /api/auth/sso/entra/exchange. See Authentication in the reference.

Environments and base URL

Testing

For the Partner API reads and webhooks, use the sandbox: a sandbox API key on the production base URL reads simulated sites, devices, telemetry and alerts, and sends signed sample events. It reaches no real organisation, device or market.

The sandbox does not cover operations that take an access token, such as telemetry ingestion. For those, AmpVerve provisions a dedicated non-production organisation on production infrastructure. It is a real tenant with real isolation.

• Ask for a non-production organisation through Request API access. You get separate credentials.
• Prefix test identifiers so test data is obvious, for example test-site-0001-inverter-1.
• Never write test data into a production organisation. Credential writes that look like placeholders are rejected against real tenants.
• Operations labelled Demo environment act on synthetic devices in demo organisations only.

Sandbox Live

Build and test against simulated sites and devices, with a key that cannot reach a real home, site, device or market.

Every organisation has one sandbox: a separate organisation in the demo realm, demo-sandbox-<16 hex>, derived from your own. A sandbox key is an ordinary avk_ key issued for that organisation. There is no separate host: send it to https://app.ampverve.com and the key selects the sandbox.

What the sandbox contains

• Telemetry every 5 minutes, generated from the clock in UTC: solar a half sine from 06:00 to 18:00, the battery charging from 09:00 to 15:00 and discharging from 17:00 to 21:00, the chargers charging overnight.
• Alerts: depot charger 2 stops reporting two hours before the current hour and has an open comms_lost alert; a resolved solar underperformance alert from yesterday.
• Deterministic. The same request at the same moment gives the same answer, so an integration test can assert on it. GET /api/devtools/partner/v1/sandbox/scenario describes it all.
• Simulated, not measured. Nothing is stored and no value describes real equipment.

1. Issue a sandbox key

An organisation administrator calls the ordinary key operation with environment=sandbox. Every key and webhook operation takes it; sandbox keys and endpoints are listed, rotated and revoked the same way, separately from live ones.

curl -X POST "https://app.ampverve.com/api/devtools/apikeys?environment=sandbox" \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Integration tests","scopes":["alerts:read","devices:read","telemetry:read"],"expires_in_days":90}'

curl https://app.ampverve.com/api/devtools/partner/v1/me \
  -H "Authorization: Bearer $AMPVERVE_SANDBOX_KEY"

{
  "organisation_id": "demo-sandbox-a3086976a3fc5003",
  "environment": "sandbox",
  "key": { "..." }
}

2. Call the reads

Every Partner API operation answers a sandbox key with the same response shape as a live key. Scopes, expiry, revocation and the 600 requests a minute limit apply as usual.

curl "https://app.ampverve.com/api/devtools/partner/v1/telemetry/latest?asset_id=sbx-solar-inverter&hours=1" \
  -H "Authorization: Bearer $AMPVERVE_SANDBOX_KEY"

{
  "readings": [
    { "asset_id": "sbx-solar-inverter", "asset_type": "inverter", "provider": "sandbox",
      "ts": "2026-10-05T13:05:00Z", "power_kw": -46.983, "soc_pct": null,
      "energy_kwh": 3.9152, "status": "producing" }
  ]
}

3. Receive test webhooks

Register a sandbox endpoint with POST /api/devtools/webhooks?environment=sandbox and store its signing secret. Then send a sample of any event type, with the sandbox key alone, from your own test suite:

curl -X POST https://app.ampverve.com/api/devtools/partner/v1/sandbox/webhooks/test \
  -H "Authorization: Bearer $AMPVERVE_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"device.offline"}'

{
  "event_id": "evt_5c0f...",
  "event_type": "device.offline",
  "delivery_ids": ["4be1..."],
  "status": "queued"
}

The delivery is signed with AmpVerve-Signature and retried exactly like a live event (see Webhooks), and its data.sandbox is true. The event types are alert.raised, alert.resolved, device.offline and webhook.test. An administrator can also send one to a single endpoint with POST /api/devtools/webhooks/{endpoint_id}/test?environment=sandbox. Sample alert and device events are sent from the sandbox only; a live endpoint is sent webhook.test only.

Try it on this page

The six operations a sandbox key can call have a Try it panel in the reference: me, alerts, devices, latest telemetry, the scenario and the test event. Every other operation says why it has none.

• Sandbox keys only. Before it sends anything else, the panel calls GET /api/devtools/partner/v1/me with your key and stops unless environment is sandbox. A live key is refused after that one read of the key itself.
• Real requests. They go from your browser to https://app.ampverve.com, count against the key's rate limit and appear in your webhook delivery log, exactly as from your own code.
• Your key stays with you. It is held in the page while it is open, and in this browser tab's session storage only if you tick "Remember for this tab". It is never written anywhere that outlives the tab. "Forget key" clears it.
• Only these operations. The server lets https://www.ampverve.com read the answers of these six operations, with their own method and no cookies, and of nothing else.

What a sandbox key can never do

• Reach another organisation. Its organisation is fixed on the key when it is issued, in the demo realm, and no header, parameter or body field changes it.
• Reach a device. The Partner API answers a sandbox key from the simulator without reading any stored device, alert or telemetry row.
• Write to a market or command anything. A sandbox key holds read scopes only (alerts:read, devices:read, telemetry:read; a write scope is refused when it is issued), so the Home Assistant connector writes, the only other operations that take an API key, refuse it. Every other operation refuses an API key with 401, and the only Partner API operation that writes is the sandbox test event. A live key gets 403 sandbox_only on the sandbox operations.

Errors

AmpVerve uses HTTP status codes, and every error body is a JSON object with a detail field. The developer tools and Partner API operations (/api/devtools/...) also return a machine readable error object beside it.

The error envelope

{
  "detail": "API key revoked",
  "error": {
    "code": "api_key_revoked",
    "message": "API key revoked",
    "request_id": "req_4be1c0f35a2d4e7f9b8c6d5e4f3a2b1c"
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Request-Id: req_4be1c0f35a2d4e7f9b8c6d5e4f3a2b1c
WWW-Authenticate: Bearer realm="ampverve-partner-api"

• error.code is the contract: stable, snake case. Branch on it. New codes can be added; treat an unknown one by its HTTP status.
• error.message is for people. Its wording can change.
• error.request_id equals the X-Request-Id header, which every /api/devtools response carries, success or error. Log it and quote it to support. Send your own X-Request-Id (8 to 128 of A-Z a-z 0-9 . _ : -) and it is kept; otherwise AmpVerve assigns req_<32 hex>.
• detail is unchanged, so a client that reads it today keeps working.

Error code reference

Every error.code the developer tools and Partner API operations return today. A test reads the codes from the service code and fails if this table and the code disagree, so the list cannot drift. The first group are specific codes. The rest are the code of the HTTP status, used when nothing more specific applies. Where detail is an object with its own error code, that code is used.

An unexpected failure on these operations returns 500 with internal_error and a request id, never a plain text body.

The detail field everywhere else

Operations outside /api/devtools return detail only, without X-Request-Id, until the envelope is extended to them.

{ "detail": "Authorization header missing" }

// detail is an ARRAY here, one entry per field
{
  "detail": [
    { "type": "missing", "loc": ["body", "email"], "msg": "Field required", "input": {} }
  ]
}

// detail is an OBJECT on a few errors, such as a missing API key scope
{ "detail": { "error": "insufficient_scope", "required_scope": "alerts:read" } }

Common status codes

Each operation in the reference lists the status codes it documents.

Resource IDs

Treat every identifier as an opaque, case sensitive string. Do not parse meaning out of it except where this table says the format is fixed.

Other identifiers, such as alert, run and decision ids, are documented on the operation that returns them.

Pagination

Every Partner API list pages the same way: ask for a page with limit, then follow next_cursor until it is null.

Cursor pagination

• Every row once. Following next_cursor to the end reads every row once, newest first, without gaps or repeats. A row that arrives while you page is newer than your first page, so it is not in this walk; start a new walk to see it.
• Same filters on every page. Send the filters of the first page (status and since, asset_id and hours) with every page. A cursor sent with different filters, a cursor from another list, or one that cannot be read is 400 with error.code invalid_cursor. Start again without a cursor.
• Telemetry windows do not slide. hours counts back from the time of the first page, and later pages keep that window, so a slow walk does not lose readings at the far end.
• Opaque. Do not build, parse or keep a cursor beyond its walk; its format can change. It names no organisation and grants nothing: every page is read for your key's own organisation.
• The sandbox pages the same way, so a loop tested against a sandbox key works unchanged with a live key.

Read every page

These loops are generated from the live specification and print every item of every page as one JSON line. They need only the standard library (the shell loop needs curl and jq) and read the key from AMPVERVE_API_KEY. A test runs each of them against a server that pages the same way. The SDKs have helpers that do this for you: iter_devices() in Python and iterDevices() in TypeScript.

Compatibility

No parameter was removed or renamed. A request without cursor returns what it returned before, the newest limit rows under the same list name, plus next_cursor and has_more. Before cursors, the way to read further was to move since back (alerts) or raise hours (telemetry). That still works, but is deprecated as a way to page; both stay as filters. Use cursor.

Other operations

Outside the Partner API, pagination is not uniform yet. Check each operation's parameters rather than assuming.

Rate limits

Rate limit headers Live

Every response from a Partner API operation carries the key's limiter state, on success and on the 429:

Slow down as RateLimit-Remaining approaches zero rather than waiting for a 429. The window is one minute per key, shared by every AmpVerve server, so several processes using one key share its limit. Access token operations and the Home Assistant connector operations do not carry these headers yet. No other general limit is published; where an individual operation has its own limit, its reference entry says so. Honour Retry-After whenever it is present and back off exponentially with jitter.

Versioning and changelog

The API is date versioned. The current version is loading, the specification's info.version, and webhook payloads carry it as api_version. Paths are not versioned except where a family says so, such as /api/devtools/partner/v1.

What can change without a new version

• A new operation, a new optional request field, or a new field in a response.
• A new enum value in a field documented as extensible.

Your client must tolerate these: ignore unknown response fields, and never assume an enum is closed unless the reference says so.

What needs a new version or a migration window

• Removing or renaming a field, or changing its type, unit, sign or meaning.
• Making an optional request field required, or tightening an enum.
• Changing authentication or the status code for an existing condition, or removing an operation.

Before an operation is removed or changed in a way that is not additive, it is deprecated with at least 6 months' notice. See Deprecation.

Changelog

Generated from the dated sections of the live specification. Follow it in a feed reader: changelog.atom (Atom 1.0) carries the same entries, newest first, each linking back to its entry here.

Deprecation

An operation you build against is not removed or broken without at least 6 months' notice, and every response it gives during that time says so in machine readable headers.

What happens when an operation is deprecated

• The changelog records the announcement date, the replacement and the sunset date, the last day the operation is served.
• The specification marks the operation deprecated: true with x-ampverve-deprecated-on, x-ampverve-sunset and x-ampverve-replacement (the operationId to move to), and the reference shows a Deprecated label and a Deprecation row on it.
• From the announcement, every response of the operation, successful or not, carries the headers below.
• Each organisation with an active API key that can call the operation (not revoked, not expired, and holding the operation's scope) gets an organisation alert, partner_api_operation_deprecated. It appears in the console's alert list, in GET /api/devtools/partner/v1/alerts, in your alert routing rules, and as an alert.raised webhook. AmpVerve does not record which organisation called which operation, so the alert goes to every organisation whose keys could call it, not only to those that did.
• The operation stays served unchanged until the end of the sunset day.

The sunset is never less than 6 calendar months after the announcement. A test in the service refuses a shorter one, and another keeps the service's list of deprecated operations equal to the specification's marks.

Deprecation headers

Log a warning, or raise an alert of your own, the first time your client sees Deprecation on a response, and plan the move before the Sunset date. Other links may share the Link header, so look for the rel="deprecation" entry rather than reading the whole value.

Scope

The headers and alerts apply to the Partner API (/api/devtools/partner/v1) and to API key and webhook management (/api/devtools/apikeys, /api/devtools/webhooks). A change that is not additive is recorded in the changelog no later than the day it ships; the 6 month notice is committed once an operation is live. No operation is deprecated today, so no response carries these headers yet.

Webhooks Live

AmpVerve sends your organisation's events to an HTTPS endpoint you register, signed so you can prove they came from AmpVerve.

Event catalogue

Every event type AmpVerve sends to the endpoints you register. Each links to its reference entry, which has the full example payload and headers. A test checks this list against the dispatcher and the specification.

Every event has the same envelope, serialised with sorted keys and no spaces: id (evt_ and 32 hex, stable across retries), type, api_version, organisation_id, occurred_at and data. An event is only ever sent to endpoints of the organisation it belongs to. The alert's message and context are never sent, because they can hold personal data. A sample sent from the sandbox carries "sandbox": true in data.

Register an endpoint

Organisation administrators only, in Settings, API access or with POST /api/devtools/webhooks. The URL must be https on port 443 or 8443, on a public host name or address; private, loopback, link-local and internal names are refused, the check runs again before every delivery, and redirects are not followed. At most 10 endpoints per organisation. The signing secret (whsec_...) is returned once.

curl -X POST https://app.ampverve.com/api/devtools/webhooks \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/ampverve","event_types":["alert.raised","alert.resolved","device.offline"]}'

{
  "id": "evt_5c0f...",
  "type": "alert.raised",
  "api_version": "2026-10-03",
  "organisation_id": "...",
  "occurred_at": "2026-10-03T14:35:02Z",
  "data": { "alert": { "..." } }
}

AmpVerve-Signature: t=1759500000,v1=<64 lowercase hex characters>
AmpVerve-Webhook-Id: evt_5c0f...
AmpVerve-Delivery-Id: <delivery id>
AmpVerve-Event-Type: alert.raised
Content-Type: application/json

The full payload of each event is in Webhook events in the reference.

Verify the signature

AmpVerve-Signature is t=<unix seconds>,v1=<hex>, where v1 is the hex HMAC-SHA256 of "<t>." + raw body keyed with the whole whsec_... secret as UTF-8. Accept a delivery when any v1 matches and t is within 300 seconds of now.

• Compute over the raw request bytes. Parsing and re-serialising the JSON changes the bytes.
• Compare in constant time.
• After a secret rotation, deliveries carry two v1 values for the grace period (default 24 hours, at most 72), one per secret.

The samples below are standard library only, except that Ruby uses openssl, which ships with it. A test signs bodies with AmpVerve's own signer and runs every one of them: a valid delivery, a delivery during a secret rotation, a changed body, a wrong secret and a stale timestamp.

import hashlib
import hmac
import time


def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """True when an AmpVerve-Signature header is valid for the raw body."""
    parts = [p.strip().split("=", 1) for p in header.split(",") if "=" in p]
    ts = next((v for k, v in parts if k == "t"), "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    expected = hmac.new(secret.encode("utf-8"), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v) for k, v in parts if k == "v1")

import crypto from "node:crypto";

// True when an AmpVerve-Signature header is valid for the raw body (a Buffer).
export function verify(rawBody, header, secret, tolerance = 300) {
  const parts = header.split(",").map((p) => p.trim().split("="));
  const ts = (parts.find(([k]) => k === "t") || [])[1] || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(`${ts}.`), rawBody]))
    .digest("hex");
  return parts.some(([k, v]) => k === "v1" && v && v.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

// Verify reports whether an AmpVerve-Signature header is valid for the raw
// request body. Call it with tolerance 300 * time.Second.
func Verify(rawBody []byte, header, secret string, tolerance time.Duration) bool {
	var ts string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(part), "=")
		if !ok {
			continue
		}
		switch k {
		case "t":
			ts = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	t, err := strconv.ParseUint(ts, 10, 63)
	if err != nil {
		return false
	}
	if d := time.Since(time.Unix(int64(t), 0)); d > tolerance || d < -tolerance {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "."))
	mac.Write(rawBody)
	expected := []byte(hex.EncodeToString(mac.Sum(nil)))
	for _, s := range sigs {
		if hmac.Equal(expected, []byte(s)) {
			return true
		}
	}
	return false
}

require "openssl"

# True when an AmpVerve-Signature header is valid for the raw body.
def verify(raw_body, header, secret, tolerance = 300)
  parts = header.split(",").map { |p| p.strip.split("=", 2) }
  ts = parts.find { |k, _| k == "t" }&.last.to_s
  return false unless ts.match?(/\A\d+\z/) && (Time.now.to_i - ts.to_i).abs <= tolerance
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, ts + "." + raw_body.b)
  parts.any? { |k, v| k == "v1" && v && OpenSSL.secure_compare(expected, v) }
end

# verify BODY_FILE HEADER SECRET: exit status 0 when the signature is valid.
# For testing and debugging: the final comparison is not constant time, and
# the secret is visible to other processes. Use a library above in production.
verify() {
  local ts now expected
  ts=$(printf '%s' "$2" | tr ',' '\n' | sed -n 's/^ *t=//p' | head -n 1)
  case "$ts" in ''|*[!0-9]*) return 1 ;; esac
  now=$(date +%s)
  [ $((now - ts)) -le 300 ] && [ $((ts - now)) -le 300 ] || return 1
  expected=$({ printf '%s.' "$ts"; cat "$1"; } | openssl dgst -sha256 -hmac "$3" | sed 's/^.*= *//')
  printf '%s' "$2" | tr ',' '\n' | sed -n 's/^ *v1=//p' | grep -qx "$expected"
}

Delivery and retries

Retry schedule

The delay before each attempt, after the attempt before it failed. Each delay is up to 10 percent longer with jitter, and an attempt starts within about 5 seconds of falling due. After the tenth failed attempt the delivery is marked failed and is not tried again. A test computes this table from the dispatcher's own constants.

Respond 2xx quickly and process asynchronously. Persist the event before you acknowledge it, and fetch the current resource when ordering matters, because deliveries are not ordered.

Connect

Bring sites, assets and devices into AmpVerve and start the data flowing. A site is a physical location; an asset is the thing telemetry is about.

• Sites. Create a site from a template, confirm the proposed device mapping, and run the commissioning checks.
• Assets and devices. Register assets, read connected vehicles and smart meters, and the fleet telematics feed.
• Telemetry. Push records from your own systems with the ingestion operation, or from a site gateway with the offline buffer replay.

Vendor account connections, such as vehicle and Home Assistant links and the consent that goes with them, are made in the AmpVerve app. Their connection flows are not part of this public API yet.

Monitor

Read back telemetry, see which devices are healthy, account for each site's energy, and act on alerts ranked by their cost per day.

Optimise

Price every half hour against the full GB charge stack, plan battery schedules and import limits, and record why each decision was made. Optimisation is advisory and on demand; control writes act on demo realm devices only today.

Flex and markets

Read DNO flexibility tenders and awarded contracts, submit offers, and enrol sites in AmpVerve's own VPP. Market actions are partner-gated: each market needs its own credentials, commercial access and qualification before an offer can succeed. The operations below are GB markets: see Market and region coverage for what is live where, and the country capability and market guides before describing a market to a customer.

Settle and report

Turn activity into auditable records: the per period energy ledger with its source tree, PPA statements, Scope 2 and avoided emissions, signed energy receipts, and a full export of your organisation's data.

Developer tools

Keys, webhooks and the platform around them: issue and rotate API keys, register webhook endpoints, read the Partner API, and check platform status and your audit trail.

SDKs

Typed clients for the Partner API, the operations an avk_ API key can call including the sandbox routes, each with a webhook signature verifier tested against the server's own signer. Version 1.1.0.

pip install https://app.ampverve.com/api-docs/sdks/ampverve-1.1.0-py3-none-any.whl

npm install https://app.ampverve.com/api-docs/sdks/ampverve-sdk-1.1.0.tgz

Sizes and sha256 checksums are in manifest.json. Every other operation takes an access token and is not in the SDKs; the OpenAPI document works with standard generators for those.

Connect a site

1. List the site templates available to your organisation: GET /api/hardware/sites/templates.
2. Create the site from a template. AmpVerve discovers devices and proposes a point mapping: POST /api/hardware/sites/from-template.
3. Review and confirm the mapping, which stops the onboarding clock: POST /api/hardware/sites/{site_id}/confirm-mapping.
4. Run the commissioning checks and read the result: POST /api/hardware/data-integrity/commissioning/run.

Stream telemetry

1. Register each asset once, with a namespaced asset_id: POST /api/twin/.
2. Send batches with an access token: POST /api/telemetry/ingest. Check that stored equals count on every response.
3. Confirm the data landed: GET /api/telemetry/live/events, or read history for one asset.
4. Poll readiness every 30 to 60 seconds and buffer when it degrades. Read Getting data in before building.

Get alerts

1. Register a webhook endpoint for alert.raised, alert.resolved and device.offline, and store the signing secret: see Webhooks.
2. Send yourself a test event and check the delivery log.
3. Verify every delivery's signature, acknowledge with 2xx, and deduplicate on the event id.
4. To poll instead, read the ranked queue with an access token, or the Partner API alerts with an alerts:read key.

Offer flexibility

1. Read your aggregate portfolio capacity.
2. Read the open DNO flexibility tenders.
3. Submit an offer against a tender.
4. Read the contracts you have been awarded.

Get paid: settlement records

1. Read the stored energy ledger per settlement period, and open any row to see its full source tree.
2. Read the monthly PPA statement for a site.
3. Issue signed energy receipts where a counterparty needs evidence.
4. Export the organisation's data in open formats for your own finance system.

Residential and home energy apps

For apps that show a household its vehicle, meter, tariff and carbon in one place. These are the operations AmpVerve's own home app calls.

Fleet and depot

For operators who need every vehicle ready for its next departure within the depot's supply limits. These are the operations AmpVerve's fleet views call.

C&I and EMS platforms

For EMS, BMS and solar platforms that onboard commercial sites, report energy and carbon with lineage, price consumption against the GB charge stack, and act on alerts. These are the operations AmpVerve's EMS views call.

Getting data in

Read this section fully before writing an ingestion client. The behaviours below change how you should design retries, deduplication and alerting.

curl -X POST https://app.ampverve.com/api/telemetry/ingest \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"asset_id":"site-0412-inverter-1","ts":"2026-10-03T14:00:00Z","power_kw":-4.812,"voltage":241.3,"status":"producing"},
    {"asset_id":"site-0412-battery-1","ts":"2026-10-03T14:00:00Z","power_kw":2.4,"soc_pct":68.5,"status":"charging"}
  ]'

// 200 does not mean persisted: check stored == count, and anomalies
{ "count": 2, "stored": 2, "streamed": 2, "anomalies": [] }

Telemetry schema and units

Fields AmpVerve recognises are mapped onto canonical, indexed columns. Everything else is preserved in a raw JSON column. Only canonical fields are aggregated and surfaced by the read operations.

Common unit mistakes

Sites and assets

An asset is what telemetry is about. A site groups assets at one physical location. Register assets once, then stream against them.

curl -X POST https://app.ampverve.com/api/twin/ \
  -H "Authorization: Bearer $AMPVERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"site-0412","type":"inverter","name":"site-0412-inverter-1","details":{"rated_kw":7.6}}'

• site_id is yours. Use your own stable site key so your systems and AmpVerve agree without a translation table.
• asset_id must be unique within your organisation, not just within a site. Namespace it: site-0412-inverter-1, not inverter-1.
• Never reuse an asset_id for different hardware. History is keyed on it.
• Keep it stable across firmware and vendor portal changes; record a changed serial in details.

Timestamps and timezones

ts is client supplied and is the basis for bucketing, ordering and every query.

• Store and send UTC. Convert vendor local time with a timezone database, never by adding a fixed offset; British Summer Time duplicates an hour in autumn and drops one in spring.
• Timestamps are not deduplicated. Two records with the same asset_id and ts both persist.

Batching and backfill

• Send an array. A batch is written in one database transaction: every row lands or none do.
• Batches of 100 to 1000 records work well. Above a few thousand you widen the blast radius of one failed transaction. There is no server enforced record cap; keep a request body under 5 MB.
• Prefer one batch per site per interval, so a failure is attributable to one site.
• Backfill is the same call with older timestamps. Writes older than 30 days may land in compressed storage and be refused; agree a large backfill with AmpVerve first. Backfilled records appear in the live stream like fresh ones.

Idempotency and ordering

On a timeout or a 5xx you do not know whether the write landed. Either verify then retry (query GET /api/telemetry/live/events?asset_id=... for the batch's timestamps before resending), or accept at least once and deduplicate on read by (asset_id, ts).

• Records within one batch are written in array order; concurrent batches interleave.
• The live event stream is ordered by arrival. Read operations order by ts.

Idempotency keys Live

One operation accepts an Idempotency-Key header today: POST /api/devtools/partner/v1/sandbox/webhooks/test, the only operation that writes with an API key. No other write accepts it yet, and telemetry ingestion has no deduplication, as above.

• Same key, same request: nothing new is queued. You get the first 202 body again, with Idempotent-Replayed: true.
• Same key, different request (another event_type or endpoint_id): 409. Use a new key.
• Only success is remembered. A request that failed queued nothing, so a retry with the same key is a fresh attempt.
• Scope and lifetime. Keys are per organisation, not per API key, and are remembered as long as the event is kept. 1 to 255 visible ASCII characters; a UUID per intended request is ideal. AmpVerve stores a hash of the key, not the key.

Detecting bad data

Watch three independent signals.

1. The anomaly report, per record

2. The persistence check, per batch

3. The readiness probe, platform wide

Poll GET /api/telemetry/readyz every 30 to 60 seconds. It is unauthenticated. 200 with checks.database false means writes are accepted but not persisted; 503 means stop writing and back off.

There is no per site data health operation. Monitor per site staleness yourself, or subscribe to device.offline webhooks.

Getting started with the AmpVerve API

The AmpVerve API supports integrations for homes, commercial and industrial sites, fleets, data centres, energy suppliers, CPOs, CSMS providers, EMS and BMS platforms, OEMs and market partners. The same tenant boundary applies to every audience. Product access does not imply that every asset can be controlled or that every country has an active revenue programme.

Choose an integration path

Current production base URL

https://app.ampverve.com

It is the only base URL. No other AmpVerve API hostname resolves; do not place any other in a client configuration. The sandbox is selected by a sandbox API key on this same base URL.

Make the first verified call

Check readiness without credentials:

curl --fail-with-body \
  https://app.ampverve.com/api/telemetry/readyz

Obtain a 60 minute bearer token. Use a dedicated integration user in a dedicated organisation. Never share an administrator's interactive account with a service.

curl --fail-with-body \
  -X POST https://app.ampverve.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"integration@example.com","password":"<secret>"}'

Send telemetry only after the identifiers and units in RESOURCE_AND_ASSET_MODEL.md are agreed:

curl --fail-with-body \
  -X POST https://app.ampverve.com/api/telemetry/ingest \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '[{
    "asset_id":"site-0412-battery-1",
    "ts":"2026-08-20T16:30:00Z",
    "power_kw":2.4,
    "soc_pct":61.2,
    "status":"charging"
  }]'

Treat the response as successful only when stored equals count. A 200 response with stored: 0 means the service accepted and streamed the records but did not durably store them. Check readiness, buffer the source records and follow the ambiguity guidance in PLATFORM_CONTRACTS.md before retrying.

Authentication and tenant isolation

The main credential is a bearer JWT obtained with email and password. An organisation administrator can also issue an organisation API key (POST /api/devtools/apikeys, or Settings, API access in the console). A key is sent as Authorization: Bearer avk_..., is accepted only by the read operations under /api/devtools/partner/v1 (scopes alerts:read, devices:read, telemetry:read) and by the Home Assistant connector operations under /api/telemetry/connectors/home-assistant/v1 (scope telemetry:write), and is shown once at creation. Signed webhooks for alert.raised, alert.resolved and device.offline are registered at /api/devtools/webhooks; the signature scheme is in openapi.yaml under webhooks. Ingestion still takes the JWT. OAuth client credentials and delegated end user tokens are planned.

The authenticated token selects the organisation. Do not rely on a UI, client supplied organisation_id, or an X-Tenant-ID header to enforce isolation. A partner client should:

1. keep separate credentials and storage for every organisation;
2. never reuse an idempotency key across organisations;
3. treat 403 tenant mismatch as a security incident, not a retryable error;
4. preserve organisation_id, site_id, asset_id, request id and event id in

its own audit trail;

5. use synthetic tenants and assets for tests.

Production access checklist

Before sending customer data, agree all of the following with AmpVerve:

• organisation and environment identifiers;
• data controller and processor roles;
• authentication and credential rotation owner;
• permitted asset classes, commands and countries;
• consent capture and revocation flow;
• expected telemetry frequency, units, backfill and retention;
• support contacts and incident severity definitions;
• rate limits and expected burst size;
• market, settlement and payout gates, if revenue features are in scope;
• rollback and offboarding procedure.

Tools

The checked in ../openapi.yaml and ../openapi.json are the canonical machine contracts. Import the JSON file into Postman, Insomnia or an OpenAPI code generator. Generated clients are not official AmpVerve SDKs. Pin the specification commit, review generated diffs and keep transport retry behaviour outside generated model code. There are no published npm, PyPI, Maven, NuGet, Swift or Go SDK packages today.

Global capability discovery

AmpVerve is designed as a global platform. Global design is not the same as global activation. Country, asset, connection, optimisation, control, market, settlement, payout and carbon capabilities must be discovered independently.

The public contract must never answer the question "is this country supported?" with one boolean. A user may be able to download the app and connect telemetry while smart control, flexibility revenue or carbon monetisation remains unavailable.

Capability dimensions

Resolve capability from all of these inputs:

• ISO 3166-1 alpha-2 country code;
• subdivision, postcode, utility territory or grid zone;
• organisation and contract;
• customer segment: residential, commercial, industrial, fleet or data centre;
• site import, export and connection agreement;
• asset class, make, model, firmware and connectivity path;
• consent and delegated control authority;
• tariff and meter data source;
• market partner, programme, qualification and enrolment;
• telemetry freshness and control verification;
• settlement currency, tax information and payout corridor.

Capability discovery

There is no capability discovery operation in the API today. Country, asset and market capability is agreed per organisation with AmpVerve, using the country and market guides as the starting point. Unknown or unverified coverage is an explicit unavailable answer: AmpVerve never falls back to GB or infers market access from locale.

Availability states

Country guides

The country catalog lives in ../markets/. Great Britain and the United States have evidence based guides because there is concrete repository and partnership context. Every other ISO country remains research_required or planned until its market guide is completed and approved. An Axle or Leap market page is useful competitive evidence, but it is not proof of AmpVerve access.

Each country guide records:

1. market structure and named operators;
2. programme types and AmpVerve's aggregator route;
3. eligible assets and customer segments;
4. meter, telemetry and dispatch requirements;
5. baseline, verification and settlement method;
6. currency, tax and payout notes;
7. carbon method and double counting guard;
8. consent, privacy and data residency requirements;
9. technical endpoints and partner dependencies;
10. readiness state, evidence source and evidence date.

Compatibility discovery

Country availability must be intersected with asset compatibility. A brand catalog entry or protocol implementation is not sufficient. The response should identify the supported connection routes in priority order:

1. direct OEM cloud API;
2. approved aggregator connection;
3. CPO or CSMS path such as OCPP;
4. site gateway path such as Modbus, SunSpec, BACnet or MQTT;
5. utility data path such as Green Button;
6. compatibility request when none is verified.

Every route states whether it provides telemetry, scheduling, real-time control, bidirectional control or data only.

Cache and audit rules

Capability decisions can change when programme windows, provider credentials, device health or user consent change. Responses should carry evaluated_at, an evidence version and a short cache lifetime. Preserve the exact decision and requirements used for every optimisation, command, bid and customer claim.

Resource, asset and delegation model

This is the canonical model for new partner integrations. Some resources below do not yet have a public CRUD endpoint. A documented model is not proof that an API is deployed. Check ../openapi.yaml and its x-ampverve-status field before calling anything.

Resource hierarchy

partner
  organisation
    users and service identities
    portfolio or fleet
      site
        grid boundary and meters
        assets
          connection
          capabilities
          telemetry streams
          constraints and consent
          optimisation runs
          commands and verification
        programme enrolments
        dispatches
        settlement lines
        payout allocations

organisation_id is the tenant boundary. site_id is a physical or contractual boundary. asset_id identifies one controllable or observable resource within the organisation. A portfolio is a grouping, not a replacement security boundary.

Audiences and roles

The current API authorises by role, not OAuth scope. Current role names are ORG_ADMIN, OPERATOR, ANALYST, RESEARCHER and VIEWER. New partner APIs should move toward explicit permissions such as telemetry:write, assets:read, control:request and settlement:read, but those scopes are planned.

A B2B2C partner must not make every end customer an organisation administrator. Use delegated grants that record:

• grantor user and organisation;
• grantee partner or service identity;
• site and asset scope;
• capability scope, such as read telemetry or schedule charging;
• country and programme scope, where applicable;
• consent text and version;
• granted, effective, expiry and revoked timestamps;
• source channel and evidence reference.

Delegated OAuth and consent resources are planned. Until available, access is provisioned contractually and through organisation roles.

Universal asset envelope

All asset types should share a small stable envelope and put device specific data in typed capability blocks.

{
  "id": "site-0412-battery-1",
  "organisation_id": "org-123",
  "site_id": "site-0412",
  "external_id": "partner-device-987",
  "asset_type": "battery",
  "manufacturer": "example",
  "model": "example-10",
  "country_code": "GB",
  "timezone": "Europe/London",
  "connection": {
    "state": "connected",
    "provider": "oem_cloud",
    "last_verified_at": "2026-08-20T16:00:00Z"
  },
  "capabilities": [
    {"name": "telemetry.read", "state": "verified"},
    {"name": "power.setpoint.write", "state": "unavailable"}
  ]
}

The supported asset vocabulary is designed to include:

• EVs, chargers, batteries, solar and inverters;
• heat pumps, HVAC, thermostats and hot water;
• smart meters, submeters and grid boundary meters;
• fleets, depots, commercial sites, industrial loads and data centre resources;
• tariffs, utility accounts and market programme relationships.

An asset type alone never proves control. Capability must be reported and verified per connected instance. For example, a vehicle can expose battery telemetry while its paired charger provides the actual charge control path.

Capability states

Only verified permits live control, and only while freshness, consent and safety checks remain valid.

Connection and protocol paths

AmpVerve can model OEM cloud APIs, aggregator APIs, OCPP, OCPI, Modbus, SunSpec, BACnet, MQTT, OpenADR, IEEE 2030.5, Green Button and utility or tariff feeds. The presence of an adapter, protocol class or brand in source code is not evidence of production credentials, compatible firmware, geographic coverage or a tested live path.

Every connection response should disclose:

• connection_method and provider;
• credential owner and expiry, without returning secrets;
• asset and country scope;
• observed and verified capabilities;
• last successful read and command timestamps;
• health, rate limit and relink state;
• fallback mode if the provider is unavailable.

Unsupported assets

Do not return a fake connected asset or a generic success result. The integration flow for an unsupported make, model, protocol or country is:

1. accept a compatibility request with manufacturer, model, country and asset type;
2. return request_received, not connected;
3. provide a request id and status endpoint;
4. assess an existing aggregator, OEM cloud or local gateway route;
5. verify the model, account permissions, telemetry and safe command path;
6. activate only for the requesting organisation and scope;
7. notify the partner when the capability moves to verified.

Gateway onboarding follows the same rule. A gateway can widen protocol reach, but it cannot create manufacturer permission, grid approval or market qualification.

Lifecycle and deletion

Recommended lifecycle states are requested, authorising, connected, verifying, active, degraded, relink_required, revoked and offboarded. Offboarding must revoke credentials and future control immediately. Telemetry, command and settlement evidence may need retention under contract or regulation; it must not be silently deleted with the registry row.

Safe control and revenue lifecycles

AmpVerve's control model is Forecast -> Optimise -> Execute -> Verify -> Monetise. Each transition has its own evidence and failure state. A forecast or optimisation result must never be treated as proof of execution, savings or revenue.

Optimisation

An optimisation input should include the organisation, site, assets, tariff, forecast, availability, comfort or operational constraints, import and export limits, reserve, user consent and data freshness. Store the input version, solver version, objective, constraints, result and explanation.

Recommended job states are queued, running, succeeded, failed, cancelled and expired. A successful solve means a feasible plan was produced. It does not mean a device accepted or executed it.

Live control

Live asset control is fail closed. Before a command is accepted, verify:

• tenant, role and delegated authority;
• environment is production and simulation is false;
• connected asset identity and verified capability;
• fresh telemetry and current device state;
• safety, comfort, mobility and reserve constraints;
• grid connection and export limits;
• per organisation live control activation;
• idempotency key and command expiry;
• command rate and provider limits.

A command is asynchronous. The API contract should distinguish accepted, sent, acknowledged, executing, succeeded, failed, expired, cancelled and superseded. accepted is not succeeded. Verification should use post-command telemetry and preserve provider acknowledgements.

Smart charging, heating and cooling

Optimisation is available only where the connected asset supports the required read and write capabilities. Smart charging also requires a known charging boundary, user departure or ready-by intent and sufficient energy reserve. Heating and cooling require safe temperature bounds, equipment mode support and an explicit fallback when connectivity is lost.

Tariff arbitrage needs a verified tariff, timezone, tax treatment and import or export price basis. Never mix wholesale, retail, imbalance and flexibility prices without labelling the source and unit.

V2H and V2G

Vehicle telemetry or ordinary charger control does not prove bidirectional capability. V2H or V2G execution additionally requires:

• a compatible EV and bidirectional charger pair;
• firmware, protocol and installation support;
• site export permission and grid limits;
• user reserve, mobility schedule and consent;
• an exercised charge and discharge command path;
• a programme that accepts the asset and metering arrangement for V2G revenue.

V2H savings and V2G market revenue are different products and should be reported separately.

Market access gate model

Use these states for each country, programme and organisation:

The founder's Leap relationship in the USA and work with UK DNOs, NESO and Elexon are relevant market-access evidence. They do not by themselves make a country or programme live. As of 2026-08-20, the Leap connector changes are on open PRs rather than enterprise/main. The public API must describe the route as partner-gated until connector deployment and the remaining gates are verified.

Dispatch processing

Dispatch consumers must handle updates, cancellation, overlapping events, priority and duplicate delivery. Store the external event id, version, market, programme, site or group, start and end, requested direction and quantity, received time and raw payload hash. Acknowledge receipt quickly, process asynchronously and reject commands outside the allowed window.

Simulation and communication-test events need explicit flags and separate ledgers. They must not reach live devices or revenue reporting unless a controlled test authorisation says so.

Metering, baseline and settlement

For each dispatch preserve:

• raw meter and asset intervals with provenance;
• timezone, interval boundary, unit and sign convention;
• missing, estimated, substituted and corrected quality flags;
• baseline method and version;
• delivered quantity and performance calculation;
• market statement and settlement version;
• variance, dispute and correction history;
• gross revenue, fees, taxes, customer share and currency;
• link from every payout line to settled evidence.

Settlement ingestion and calculation do not authorise payout. Payout must be a separate idempotent, approved operation that fails closed when payee, tax, currency or bank configuration is incomplete.

Carbon

Operational carbon estimates can use timestamped grid intensity and measured energy. Label them as estimates with geography, source, methodology and data quality. Carbon monetisation additionally requires an accepted methodology, additionality, ownership, double counting prevention, verification, registry or buyer, issuance and settlement. Until those gates are complete, the API must not call an estimate a credit or report saleable revenue.

Platform integration contracts

This guide defines the cross-cutting behaviour every public API family should share. Where the current deployed API differs, ../openapi.yaml is authoritative and the difference is called out below.

Request metadata

Partners should send:

• Authorization: Bearer <token> for protected routes;
• Content-Type: application/json for JSON bodies;
• Idempotency-Key for retryable writes once the endpoint documents support;
• X-Request-ID with a unique value for tracing, when supported;
• traceparent when distributed tracing is agreed.

AmpVerve responses should return a request id and rate limit headers. These headers are target behaviour, not a promise for every current endpoint.

Errors

The current API generally returns FastAPI's {"detail": ...} envelope. The stable coded envelope is planned:

{
  "error": {
    "code": "AV-CONTROL-4091",
    "message": "Asset capability is not verified",
    "request_id": "req_01J...",
    "retryable": false,
    "details": {
      "asset_id": "site-0412-battery-1",
      "required_capability": "power.setpoint.write"
    }
  }
}

Retry only when the operation and error are explicitly retryable. Do not retry authentication failures, tenant mismatches, missing consent, invalid constraints or rejected market actions.

Idempotency

Current telemetry ingestion has no server side idempotency or duplicate detection. Verify ambiguous outcomes before resending.

One operation supports Idempotency-Key today: POST /api/devtools/partner/v1/sandbox/webhooks/test, the only operation that writes with an API key. A repeat of the same request with the same key in the same organisation queues nothing and returns the first 202 body with Idempotent-Replayed: true; the same key with a different event_type or endpoint_id is 409. Only a request that queued an event is remembered. The key is kept, as a hash, on the event it created, for as long as the event is kept.

For every future write:

• keys are scoped by organisation, route and caller;
• the same key and body return the original result;
• the same key with a different body returns 409;
• the retention window is documented per endpoint;
• command, bid, settlement and payout writes require idempotency;
• webhook consumers deduplicate on event id.

Pagination

The Partner API lists (GET /api/devtools/partner/v1/alerts, /devices and /telemetry/latest) and the webhook delivery log (GET /api/devtools/webhooks/{endpoint_id}/deliveries) use one cursor pagination. Each takes limit (the page size; default and maximum stated per operation) and an opaque cursor, and answers with its list under its own name plus next_cursor (null on the last page) and has_more:

{
  "devices": [],
  "next_cursor": "opaque",
  "has_more": true
}

Follow next_cursor until it is null, sending the first page's filters with every page. Each walk reads every row once, newest first, ties on time broken by the row's identifier. A cursor that cannot be read, belongs to another list or comes with different filters is 400 invalid_cursor. The telemetry window is fixed by the first page. A request without cursor returns the same rows as before pagination. Paging by moving since (alerts) or raising hours (telemetry) still works but is deprecated as a way to page. The sandbox pages the same way, and the SDKs have iter_* (Python) and iter* (TypeScript) helpers. The public Pagination page has a loop in five languages.

Elsewhere pagination is not uniform yet. Some lists return the complete set (API keys and webhook endpoints among them), some use limit, and some use offset or page and page_size. Check each operation.

Clients must treat cursors as opaque and keep stable sort order. Time-series clients should also store the timestamp and source identifier at the page boundary to detect late corrections.

Rate limits

Login is currently limited to five attempts per minute per source IP. Other limits vary by service and plan. Honour Retry-After and use exponential backoff with jitter. Request an agreed ingestion limit before production load testing.

Do not poll high consequence state when a supported webhook exists. Do not exceed an OEM's documented command budget merely because AmpVerve accepts a request.

Asynchronous jobs

Optimisation, connection, backfill, bulk enrolment, dispatch allocation, settlement and export operations should use a common job envelope:

{
  "id": "job_01J...",
  "type": "optimisation",
  "state": "queued",
  "submitted_at": "2026-08-20T16:30:00Z",
  "expires_at": "2026-08-20T16:35:00Z",
  "links": {"self": "/api/platform/v1/jobs/job_01J..."}
}

Jobs are organisation scoped, cancellable only where safe, and immutable after terminal state. Results keep input and algorithm provenance. A timeout while polling a job does not cancel it.

Webhooks

An organisation administrator registers an HTTPS endpoint with POST /api/devtools/webhooks and subscribes it to alert.raised, alert.resolved or device.offline. Each endpoint has its own signing secret, shown once at registration and stored encrypted; deliveries are signed with AmpVerve-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + raw body>, retried with backoff, and go only to endpoints of the organisation the event belongs to. The schema and headers are under webhooks in the OpenAPI document. Each webhook operation's status label in the reference says whether it is live or available after scheduled maintenance.

The EMS alert routing webhook channel, described under Alerts and events below, is separate. It does not follow this contract: it is a single attempt with no retry, and its signature carries no timestamp.

The delivery contract. Partner webhooks implement every item except replay by id or time range, which is not offered:

• HTTPS endpoints and explicit event subscriptions;
• HMAC-SHA256 signatures over timestamp plus raw body;
• timestamp tolerance and multiple signatures during secret rotation;
• stable event id, type, version, creation time and organisation id;
• at-least-once delivery with documented retries;
• replay by id or time range;
• test events clearly separated from production events;
• dead-letter visibility and disablement after persistent failure.

Receivers should authenticate before parsing, persist the event before returning 2xx, deduplicate by id, process asynchronously and fetch the current resource when ordering matters.

Alerts and events

This section states what alert and event data exists today, how a partner gets it. Paths are relative to https://app.ampverve.com. Every operation named here is scoped to the organisation in your token; its status label in the reference says whether it is live.

What exists

• EMS alerts. POST /api/hardware/ems/alerts/evaluate runs six sources over stored telemetry and raises or updates one alert per condition, priced in pounds per day where an MPAN and tariff allow: underperformance (a sustained PV shortfall), stopped_asset (an inverter reporting zero through a day generation was expected), comms_gap (half hours with no meter reading, or a gateway heartbeat loss), asset_silence (half hours with no reading from the site's PV or battery), commissioning_failure (a failed commissioning check) and export_limit_breach (measured export above the site's limit). Severity is critical, warning, info, low or unpriced, set by the organisation's pounds per day thresholds.
• Alert lifecycle. An alert is open until resolved. Acknowledge, assign, resolve and comment are separate, attributed actions: POST /api/hardware/admin/alerts-history/{alert_id}/acknowledge, /assign, /resolve and /comment. GET /api/hardware/admin/alerts-history/stats reports volumes, response times, unowned alerts and alerts closed without a note. The full cross organisation history list is for AmpVerve platform staff only.
• Device health. GET /api/hardware/devices/health returns every connected device with its last poll, last success, consecutive failures, whether the integration needs relinking, and a freshness band (healthy, stale, dark, never_worked, pending) judged against that device's own cadence. Device health problems also appear as alert rows in the EMS alert queue.
• Notifications. GET /api/notifications/ lists the in app notifications addressed to the calling user, with an unread count, mark read and preferences. Each user sees only their own; VIEWER is refused.

How to get it today

1. Poll. GET /api/hardware/ems/alerts returns every open alert of the organisation ranked by pound impact per day, including rows raised by the device health poller. Add include_resolved=true to see closed alerts, and site_id to narrow. Alerts are only raised when an evaluation runs, so call POST /api/hardware/ems/alerts/evaluate first, or on your own schedule.
2. Push, by arrangement. An EMS routing rule (/api/hardware/ems/routing/rules) can deliver alerts to email, a Microsoft Teams incoming webhook, or a generic webhook URL. The webhook body carries kind, alert_id, organisation_id, site_id, site_name, alert_type, severity, title, message, impact_gbp_per_day, monetary_impact_gbp, band_reason, root_cause, parent_alert_id, created_at and policy_id, with the headers X-AmpVerve-Kind (alert or escalation) and, when AmpVerve has provisioned a signing secret for the rule, X-AmpVerve-Signature: sha256=<hex HMAC-SHA256 of the raw body>. Ask your AmpVerve contact to provision the secret; it cannot be set through the API.

The webhook's limits, stated plainly:

• one attempt, a 10 second timeout, no retry; a non 2xx answer is logged as failed in GET /api/hardware/ems/routing/deliveries and not resent;
• it fires only when routing is called: by an evaluation (newly raised alerts), by POST /api/hardware/ems/routing/dispatch, or by POST /api/hardware/ems/routing/escalations/check. No scheduler calls these yet;
• each rule delivers an alert once, so deduplicate on alert_id and kind;
• the signature carries no timestamp and so does not by itself prevent replay.

For your own organisation's events

• Partner webhooks for your own organisation's events: register at POST /api/devtools/webhooks; see the Webhooks section above. Replay by id or time range is not offered.
• API keys: keys minted at POST /api/devtools/apikeys authenticate only the read operations under /api/devtools/partner/v1, for the key's own organisation. Every other operation still needs a bearer token.

Audit and provenance

Every high consequence operation should be traceable across:

request -> decision -> job -> command or bid -> provider acknowledgement -> telemetry verification -> settlement -> payout

Preserve organisation, actor, delegated authority, environment, timestamps, inputs, outputs, constraints, algorithm and connector versions, raw partner references, evidence hashes and correction history. Audit data is append-only and tenant scoped. Redact secrets and personal data from logs.

OpenAPI, Postman and SDKs

The OpenAPI JSON can be imported into Postman or used with standard generators.

SDKs for Python (sdks/python/) and TypeScript (sdks/typescript/), version 1.0.0, are thin, hand-written clients for the Partner API only (the operations an avk_ key can call under /api/devtools/partner/v1, including the sandbox routes) plus a webhook signature verifier tested against the server's own signer. The console serves the built packages at https://app.ampverve.com/api-docs/sdks/:

pip install https://app.ampverve.com/api-docs/sdks/ampverve-1.0.0-py3-none-any.whl
npm install https://app.ampverve.com/api-docs/sdks/ampverve-sdk-1.0.0.tgz

They are not published to PyPI or npm. Before publishing to a package registry, AmpVerve needs:

1. a stable versioned base URL;
2. consistent error, pagination and idempotency contracts;
3. generated and handwritten tests against an isolated sandbox;
4. package ownership, signing and vulnerability handling;
5. release notes and deprecation policy.

Until then, clients generated from the full specification are partner-owned artifacts. Do not publish registry installation commands (pip install ampverve, npm install @ampverve/sdk) under the AmpVerve name.

Versioning, changelog and deprecation

Additive response fields can ship without a new path version. Clients must ignore unknown fields. Removing or renaming a field, changing meaning, tightening an enum or changing auth requires a new version or a documented migration window.

Every deprecation notice should state the replacement, announcement date, last supported date and migration guide. High consequence control and settlement contracts need a longer partner test window than read-only endpoints.

For the Partner API, key and webhook management, and webhook events, the policy is stated in openapi.yaml under "Partner API service level and deprecation":

• while an operation is awaiting migration, a non-additive change is recorded in a dated

changelog section no later than the day it ships;

• once it is live, a breaking change or removal gets at least 6 months'

notice: it is announced in the changelog with the replacement and sunset date, marked deprecated: true, its responses carry Deprecation and Sunset headers, and registered API key owners are emailed. It is served unchanged until the sunset date.

Additive changes need no notice.

Service levels and status

There is no SLA yet. /api/telemetry/readyz is the machine-readable ingestion readiness signal. GET /api/devtools/status (public) publishes the observed availability of each public API component from the diagnostics prober's recorded checks, including the developer tools service that serves the Partner API and webhooks. AmpVerve alerts its own operators on Partner API 5xx rate and latency and on webhook delivery lag, dead lettering and dispatcher stalls. These are measurements and internal alerts, not commitments. Contractual SLA, support response, recovery objectives and service credits belong in the signed partner agreement. Documentation should not invent them.

API environment activation runbook

This runbook records what must happen before the founder adds GoDaddy DNS. It is documentation, not authorisation to change production infrastructure or DNS.

Current state, verified 2026-08-20

infra/k8s/ingress-api-public.yaml now defines the future production API host, its separate certificate and an explicit path allowlist. It is not evidence that DNS, certificate issuance or end-to-end activation has happened. The existing app.ampverve.com manifests and TLS secret are unchanged.

Production API hostname

Complete these steps in order:

1. Review infra/k8s/ingress-api-public.yaml against every non-planned path in

openapi.yaml. Confirm there is no / catch-all and no internal control, payout, admin or planned route.

2. Validate the manifest with both client and server dry-run. The infrastructure

workflow runs server dry-run before applying it.

3. Merge the reviewed change. Let GitHub Actions deploy it. Do not apply the

manifest manually.

4. Confirm all public API ingresses have address 108.141.64.121, reference secret

tls-api-ampverve, and have only the intended host and paths:

``powershell kubectl -n ampverve get ingress ampverve-public-api-strip ampverve-public-api-esg ampverve-public-api-twin ampverve-public-api-vpp ampverve-public-api-auth -o wide kubectl -n ampverve describe certificate tls-api-ampverve ``

Ready=False can be expected before DNS exists because the HTTP-01 challenge cannot reach the ingress yet. A different ingress address is a stop condition.

1. Re-resolve app.ampverve.com immediately before the DNS change. Use its

current reserved ingress IP, not a historical value.

2. In GoDaddy DNS Management for ampverve.com, add exactly this record:

1. Do not add a forwarding rule, parking entry or second api record. Save the

A record and wait for authoritative DNS plus at least two public resolvers to return the new address:

``powershell Resolve-DnsName api.ampverve.com -Type A nslookup api.ampverve.com 1.1.1.1 nslookup api.ampverve.com 8.8.8.8 ``

1. Wait for cert-manager to finish the HTTP-01 challenge, then confirm the

certificate is ready and the presented certificate is for the API host:

``powershell kubectl -n ampverve wait --for=condition=Ready certificate/tls-api-ampverve --timeout=10m kubectl -n ampverve get certificate tls-api-ampverve -o wide curl.exe --fail-with-body https://api.ampverve.com/api/telemetry/healthz ``

Do not bypass a TLS error or temporarily serve the web-console certificate.

1. Confirm the allowlist fails closed. /, /api/hems/healthz and the planned

/api/platform/v1/capabilities route must not be served on the API host.

2. Probe every documented public path, authentication, tenant mismatch,

request-size, CORS and rate-limit behaviour on the new hostname.

3. Update openapi.yaml, client configuration and the published docs only after

the probes pass. Keep app.ampverve.com as a compatibility host during a documented migration window.

The A record target in this runbook was rechecked against the live ingress on 2026-08-20. If app.ampverve.com resolves to a different reserved ingress IP at activation time, use that current address and record the reason in the evidence bundle.

Isolated sandbox

Do not point sandbox.ampverve.com at the production ingress as a shortcut. infra/bicep/sandbox/ is a fail-closed foundation: deployment is disabled by default, it has no public ingress target, and it does not create a shared namespace in production. A usable sandbox still needs all of the following:

• separate namespace or cluster and network policy;
• separate database, object storage, queues, caches and encryption keys;
• sandbox-only identity issuer, credentials and tenant ids;
• synthetic customers, meters, tariffs, assets, programmes and settlements;
• simulated device and market connectors that cannot call production partners;
• hard blocks on live commands, bids, payouts, exports and carbon issuance;
• test webhook delivery, replay and fault injection;
• data reset and fixture versioning;
• separate observability, incident labels and support expectations;
• an environment marker on every response and audit record.

Only after the sandbox ingress and certificate are deployed should the founder create:

Do not prefill the target with 108.141.64.121. Sandbox isolation is a product and safety requirement, not a hostname convention.

Go or no-go evidence

Archive these results for each environment:

• DNS answer from at least two public resolvers;
• TLS certificate subject, issuer and expiry;
• ingress and service revision identifiers;
• liveness and readiness output;
• OpenAPI contract test result;
• unauthenticated, wrong-tenant and wrong-role negative tests;
• test asset and test webhook exercise;
• proof that sandbox cannot reach production control, market or payout systems;
• rollback owner and DNS rollback values.

ISO country capability index

The planned global capability service accepts every officially assigned ISO 3166-1 alpha-2 code listed below. This is an input catalog, not a coverage claim.

Default status for every code is research_required. Published guides can still have that status: a guide proves that official routes and activation gates were researched, not that AmpVerve has activated them.

Mobile country metadata supports localisation and disclosure work only. It does not change an energy-market status in this catalog.

All assigned alpha-2 codes

XK is used operationally by some systems for Kosovo but is not an officially assigned ISO 3166-1 alpha-2 code. Treat it as a separately governed extension, not as part of this index.

Moving a country out of research

Copy TEMPLATE.md, name it with the alpha-2 code, complete every section with primary evidence and add it to README.md. A country can have mixed outcomes, such as tariff reads available and market revenue unavailable. Never replace the capability matrix with one country-wide boolean.

GB: Great Britain

Readiness

Market structure and routes

AmpVerve's current public API exposes GB tariff and carbon intensity data. The VPP service has connector code for UK Power Networks LocalFlex and SSEN ElectronConnect. Those routes require per-tenant credentials and return a failure when credentials are absent.

NESO's Demand Flexibility Service is a separate national route. NESO publishes current service terms, procurement rules, participation guidance and an API schema. AmpVerve Ltd appears in NESO's registered provider list effective from 9 April 2026. Registration does not prove that a given customer or asset is enrolled, dispatched, measured, settled or paid.

Primary evidence:

• NESO DFS service and current documents
• NESO registered provider list
• UKPN Tender Hub
• repository connector specifications under backend/services/vpp-aggregator/connectors/

Customer and asset scope

Potential customer segments include households, commercial and industrial sites, fleets and data centres. Programme-specific terms decide actual eligibility. Potential assets include EVs, chargers, batteries, solar, heat pumps, HVAC and other controllable demand, but only assets with valid metering, consent and a verified response path can participate.

V2G additionally needs a compatible EV and charger pair, export permission and a programme that accepts the metering arrangement. Smart charging or V2H capability does not establish V2G market eligibility.

Metering, dispatch and settlement

The programme evidence pack must pin the applicable rule version. It records meter identifier, interval, timezone, sign, quality flags, baseline, event, delivered quantity, correction and settlement statement. DNO and NESO events are not interchangeable, and overlapping instructions require a primacy decision.

Elexon data can support wholesale and imbalance context. Elexon integration work or registration is not proof that AmpVerve is the settlement party for a given service. Revenue is realised only after the relevant counterparty accepts the performance and issues or confirms settlement.

Currency, tax and carbon

Amounts are represented in GBP only where the source market or contract is GBP. Customer payout needs a verified payee, contractual revenue share, tax handling and payment rail. The API does not provide tax advice.

GB grid carbon data is suitable for clearly labelled operational estimates. Carbon credits require a separate methodology, ownership, additionality, verification and double counting process.

Public AmpVerve operations

See ../openapi.yaml for the full schemas:

• GET /api/trading/prices/octopus-agile, live;
• GET /api/trading/prices/regions, live;
• GET /api/trading/prices/current, live;
• GET /api/trading/carbon-intensity, live;
• GET /api/trading/carbon-intensity/forecast, live;
• GET /api/vpp/vpp/flex/tenders, partner-gated;
• GET /api/vpp/vpp/flex/contracts, partner-gated;
• POST /api/vpp/vpp/flex/offers, partner-gated.

The repeated vpp segment is deliberate: the ingress strips /api/vpp and the service mounts these routers at /vpp/flex, so the shorter path this guide listed before 2026-09-12 is not served.

No public NESO DFS operation is in the curated OpenAPI document as of the evidence date.

Open gates

• exercise each partner API with production credentials for the exact tenant;
• complete programme qualification and enrolled-asset evidence;
• exercise notification, dispatch, cancellation and fallback paths;
• validate metering completeness and baseline version;
• reconcile a real settlement statement;
• exercise customer payout end to end;
• document primacy and stacking across DNO and NESO services.

US: United States

Readiness

Market structure and Leap route

US flexibility is not one national programme. Eligibility depends on ISO or RTO, state, utility territory, programme, customer class, meter and device. Leap's official market access page describes offerings in California, Texas, New England, New York and PJM. That is Leap coverage, not automatic AmpVerve coverage.

Leap's developer model follows a meter journey: onboard, manage, transact and monetise. Its current APIs separate meter details and enrolment, support dispatch webhooks and polling, and expose interval, performance and revenue data. AmpVerve should map that lifecycle onto its organisation, site, asset, dispatch, settlement and payout records without leaking Leap identifiers across tenants.

Primary evidence:

• Leap market access
• Leap developer overview
• Leap getting started
• Leap dispatch automation
• Leap event performance and interval data

Customer and asset scope

Potential segments include households, commercial buildings, industrial loads, fleets, charging networks and data centres. Leap supports multiple technology and programme types, but the exact programme requirements determine whether an EV, charger, battery, HVAC, heat pump, meter or other load is eligible.

Before enrolment, resolve the utility account or device programme path, customer authorisation, service address, meter identity, asset characteristics and partner reference. Store Leap meter_id and market group mappings within the owning organisation.

Dispatch and metering

Prefer authenticated webhook delivery where the programme needs short notice, with polling as recovery. Process multiple and overlapping timeslots, priorities, cancellations and test flags. Deduplicate on Leap's event identifiers and preserve the raw notification.

Performance and interval data must remain distinct from final revenue. Leap notes that analytics data can differ from revenue data frozen at settlement. AmpVerve must keep settlement versions and corrections rather than overwriting operational estimates.

Currency, tax and payout

Partner statements are expected to be denominated under the applicable US programme agreement, commonly USD, but the contract is authoritative. Customer payout requires payee onboarding, applicable reporting, revenue-share rules and an exercised payment rail. The API guide does not provide tax advice.

Carbon

US carbon estimates need a named regional factor and timestamp. Market dispatch performance is not automatically a carbon credit. Any monetisation path requires ownership, additionality, methodology, verification, registry or buyer and a double counting control.

AmpVerve technical state and open gates

There is no Leap endpoint in the curated AmpVerve public OpenAPI on the evidence date. Connector work exists in PR #12 and broader integration work in PR #38, but open code is not deployed capability.

Before any US programme is marked live:

1. reconcile and merge the connector against current enterprise/main;
2. validate production and staging credentials without exposing them;
3. map organisation-scoped sites, meters and partner references;
4. implement and test enrolment status synchronisation;
5. exercise webhook authentication, replay, cancellation and polling recovery;
6. exercise safe dispatch against synthetic and then approved pilot assets;
7. reconcile interval, baseline, performance and a real settlement;
8. exercise customer payout and correction handling;
9. publish programme-specific capability results, not a generic US available flag.

AU: Australia

Readiness

Capability separation

Official market routes

AEMO operates the NEM in Queensland, New South Wales and the Australian Capital Territory, Victoria, South Australia and Tasmania. Western Australia has the separate Wholesale Electricity Market (WEM), and the Northern Territory is not connected to the NEM.

A Demand Response Service Provider (DRSP) can classify qualifying load as a Wholesale Demand Response Unit or plant as an Ancillary Service Unit. AEMO's wholesale demand response route is aimed at qualifying large retail customers and has baseline, telemetry, aggregation and registration requirements.

An Integrated Resource Provider acting as a Small Resource Aggregator can aggregate small production or bidirectional units and may apply to classify plant for market ancillary services. This is a potential route for distributed resources, not evidence that an individual household asset is eligible.

Export remains a connection and network matter. The Australian Energy Regulator recognises two-way pricing and flexible export limits, so a retail export tariff does not override the DNSP's technical envelope.

AmpVerve activation state

The mobile catalogue contains Australian locale, currency and manufacturer metadata. The DNO registry labels the AEMO adapter as scaffold. No production AEMO credentials, participant registration, intermediary contract, classified portfolio, dispatch test, settlement statement or customer payout evidence was found on enterprise/main. No Australia-specific operation is present in the curated public OpenAPI contract.

Carbon

The Australian Carbon Credit Unit Scheme only issues units to registered, eligible projects using an approved method, with project rights, monitoring, reporting and audit obligations. An operational estimate of avoided grid emissions from smart charging is not an ACCU and must not be sold as one.

Evidence

• AEMO energy markets and systems, checked 2026-08-20
• AEMO DRSP registration, checked 2026-08-20
• AEMO Small Resource Aggregator registration, checked 2026-08-20
• AER export tariff guidelines, checked 2026-08-20
• AER flexible export limit guidance, checked 2026-08-20
• Clean Energy Regulator ACCU participation requirements, checked 2026-08-20

Open activation gates

• select NEM or WEM scope and the exact state, DNSP and retail route;
• contract with or qualify as the required AEMO participant or intermediary;
• complete asset classification, metering, telemetry, dispatch and cancellation tests;
• enforce DNSP export envelopes for every bidirectional command;
• reconcile an AEMO or intermediary statement and exercise AUD payout;
• approve a carbon method before presenting anything beyond an operational estimate.

CA: Canada

Readiness

Capability separation

Official market routes

Canada does not have one national electricity-market participation model. Activation must be determined by province, system operator, distributor and utility account.

A Green Button or device-data connection can support monitoring but does not confer IESO or AESO participant status, utility programme enrolment, dispatch authority or export permission.

AmpVerve activation state

The mobile application contains Canadian locale, CAD, Green Button and manufacturer catalogue metadata. No province-specific market contract, production operator credential, qualified portfolio, utility programme enrolment, dispatch test, settlement statement or customer payout evidence was found on enterprise/main. No Canada-specific operation is present in the curated public OpenAPI contract.

Carbon

Canada's Federal Greenhouse Gas Offset System requires an eligible protocol and reductions beyond business as usual and legal requirements. Provincial systems may differ. Smart-energy avoided-emissions estimates are not federal offset credits and must remain non-monetised without a protocol, project registration, verification, serialisation and buyer.

Evidence

• IESO market participant types, checked 2026-08-20
• IESO DER Roadmap, checked 2026-08-20
• AESO joining the energy and Operating Reserve markets, checked 2026-08-20
• BC Hydro demand response for business, checked 2026-08-20
• Hydro-Quebec demand-response programme update, checked 2026-08-20
• Canada Federal Greenhouse Gas Offset System, checked 2026-08-20

Open activation gates

• select province, utility, tariff, DSO and system operator before capability discovery;
• choose wholesale, utility programme, retail optimisation or export scope;
• obtain participant, aggregator or programme contracts and credentials;
• qualify each asset and validate dispatch, cancellation and metering;
• reconcile programme or market statements and exercise CAD payout;
• complete federal and provincial privacy, consumer and tax review.

DE: Germany

Readiness

Capability separation

Official market routes

Germany's four transmission system operators procure balancing services through the joint Regelleistung platform. A prospective Balancing Service Provider must prequalify technical units and pass the required operating evidence before it can offer a reserve product.

Section 14a of the Energy Industry Act applies network-oriented control rules to specified controllable consumption devices, including private EV charging, heat pumps, cooling equipment and storage while consuming. It provides reduced network charges in exchange for controllability. It is not a balancing-market contract and it does not by itself create a customer revenue stream.

The Federal Network Agency's Market Master Data Register requires market actors and installations such as solar and stationary battery storage to be registered. Registration does not prove dispatch qualification or export permission.

AmpVerve activation state

The mobile application includes German locale, EUR and manufacturer catalogue metadata, and the DNO catalogue contains scaffold records. Those records are discovery metadata only. No tenant-scoped German BSP agreement, prequalified unit, TSO production credential, exercised dispatch, settlement statement or customer payout was found on enterprise/main. No Germany-specific operation is present in the curated public OpenAPI contract.

Carbon

The EU Union Registry accounts for EU ETS allowances and compliance. It does not turn a household smart-energy estimate into a tradeable credit. AmpVerve would need a separately approved voluntary or compliance methodology, ownership, additionality, verification, registry and double-counting controls.

Evidence

• German balancing-service prequalification, checked 2026-08-20
• Federal Network Agency section 14a consumer guidance, checked 2026-08-20
• Federal Network Agency Core Energy Market Data Register, checked 2026-08-20
• European Commission Union Registry, checked 2026-08-20

Open activation gates

• select the balancing products and contracting BSP or become qualified;
• map every asset to market location, metering operator, DSO, BRP and portfolio;
• complete section 14a technical and commercial compliance for controlled load;
• prove export permission separately from import-side controllability;
• exercise prequalification, bidding, activation, metering, settlement and EUR payout;
• complete GDPR roles, retention and cross-border transfer review.

FR: France

Readiness

Capability separation

Official market routes

RTE operates the balancing mechanism, frequency services and capacity mechanism. Demand-side resources can participate when their operator satisfies the relevant market rules and technical requirements.

RTE's current NEBCO demand-response route, historically known as NEBEF, allows eligible consumption reductions to be valued on energy markets. A Demand Response Aggregator must sign the market participation agreement, obtain technical approval and have a balance perimeter directly or through a Balance Responsible Party. RTE verifies delivered load reduction under the selected control method, and supplier compensation rules form part of the financial path.

The fact that mainland consumption sites may be technically eligible does not mean that every household, device or aggregation is qualified.

AmpVerve activation state

The mobile catalogue lists France, EUR, Linky and manufacturer metadata. No production Linky consent flow, RTE information-system access, signed NEBCO or balancing agreement, approved portfolio, dispatch test, supplier-compensation reconciliation, settlement statement or customer payout evidence was found on enterprise/main. No France-specific operation is present in the curated public OpenAPI contract.

Carbon

EU ETS allowance accounting is not a crediting method for household energy savings. Carbon impact may be estimated only with a named factor and data basis. Monetisation remains off until a separate method, rights, verification, registry and buyer are approved.

Evidence

• RTE balancing, demand response and capacity mechanisms, checked 2026-08-20
• RTE participation in the NEBCO mechanism, checked 2026-08-20
• RTE NEBCO supplier compensation, checked 2026-08-20
• RTE 2026 market-rule versions, checked 2026-08-20
• European Commission Union Registry, checked 2026-08-20

Open activation gates

• select NEBCO, balancing, frequency or capacity product and contracting route;
• obtain RTE information-system access, agreement and technical approval;
• establish the BRP and supplier-compensation model;
• validate Linky or other metering consent, interval quality and baseline method;
• test activation, cancellation, correction, settlement and EUR payout;
• complete GDPR and French consumer disclosure review.

IE: Ireland

Readiness

Capability separation

Official market routes

EirGrid defines a Demand Side Unit as one or more Individual Demand Sites that can be instructed to reduce demand. The published setup route requires at least 4 MW for a registered DSU, permits aggregation and requires Grid Code testing. Providing units seeking system-services contracts must also demonstrate their capability through the relevant compliance and testing process.

ESB Networks procures distribution flexibility for specified needs. Its Demand Flexibility Product is location-specific and contract-based. An announced product or national policy target is not an open API or automatic residential revenue path.

The Commission for Regulation of Utilities describes dynamic tariffs available from June 2026. A dynamic retail tariff can support optimisation, but only when the customer's supplier, contract and half-hour prices are verified.

AmpVerve activation state

The mobile application contains Irish locale, EUR and manufacturer catalogue metadata. No EirGrid or SEM participant registration, qualified DSU, ESB Networks flexibility contract, production market credential, dispatch test, settlement statement or customer payout evidence was found on enterprise/main. No Ireland-specific operation is present in the curated public OpenAPI contract.

Carbon

Estimated operational carbon impact is separate from a verified unit. EU ETS registry infrastructure does not by itself credit household demand shifting. Carbon monetisation remains off until a method, rights, verification, registry and buyer are approved.

Evidence

• EirGrid Demand Side Unit setup and testing, checked 2026-08-20
• EirGrid DS3 programme, checked 2026-08-20
• ESB Networks Demand Flexibility Product, checked 2026-08-20
• CRU dynamic price tariffs, checked 2026-08-20
• European Commission Union Registry, checked 2026-08-20

Open activation gates

• choose DSU, system-services, distribution-flex or tariff-only scope;
• contract with the required aggregator or complete participant registration;
• qualify the portfolio and complete Grid Code and communication tests;
• verify MPRN, meter interval, baseline, event and correction rules;
• reconcile settlement or contract invoices and exercise EUR payout;
• document Republic of Ireland versus Northern Ireland routing and data roles.

NL: Netherlands

Readiness

Capability separation

Official market routes

TenneT procures balancing services from recognised Balancing Service Providers. FCR, aFRR and mFRR products have distinct prequalification, bidding, communications and framework-agreement requirements. Imbalance settlement and balancing-service settlement must not be treated as the same ledger.

GOPACS is a joint initiative of Dutch grid operators for congestion management. Its products include congestion-service contracts and redispatch routes. A flexibility need is location and time specific, and a market participant or Congestion Service Provider must satisfy the applicable product conditions.

A P1 port or smart-meter catalogue entry is only a possible local telemetry method. It does not confer TenneT BSP status, GOPACS access or export permission.

AmpVerve activation state

The mobile application contains Dutch locale, EUR, P1 and manufacturer catalogue metadata. The DNO registry has a TenneT scaffold record. No recognised BSP or CSP role, prequalified portfolio, production credential, live dispatch, settlement statement or customer payout evidence was found on enterprise/main. No Netherlands-specific operation is present in the curated public OpenAPI contract.

Carbon

EU ETS allowance accounting does not issue a carbon credit for shifting a home's electricity use. AmpVerve carbon monetisation remains unavailable until a separate method, ownership, additionality, verification, registry and buyer are approved.

Evidence

• TenneT aFRR manual for Balancing Service Providers, checked 2026-08-20
• TenneT BSP recognition and data-processing agreement, checked 2026-08-20
• GOPACS congestion-management platform, checked 2026-08-20
• European Commission Union Registry, checked 2026-08-20

Open activation gates

• choose TenneT reserve products, GOPACS products or both and document stacking rules;
• obtain BSP or CSP agreements and product prequalification;
• map each asset to DSO, connection, meter, BRP and congestion area;
• validate bidding, activation, cancellation and real-time communications;
• reconcile accepted performance and exercise EUR customer payout;
• complete GDPR roles, consent, retention and cross-border transfer review.

Nordics: Denmark, Finland, Norway and Sweden

Readiness

Capability separation

Official market routes

Country distinctions

Nordic balancing cooperation does not create one commercial onboarding path. Each TSO qualifies providers and resources under national terms, while products, bidding zones, currencies, balance responsibility and technical interfaces can differ.

The common Nordic mFRR and evolving European-platform work affects market design and interfaces. It does not remove the need for national agreements, prequalification, asset mapping, BRP treatment or settlement validation.

AmpVerve activation state

The mobile application contains locale, currency and manufacturer catalogue metadata for Denmark, Finland, Norway and Sweden. The DNO catalogue contains planned TSO records for Finland and Sweden. No national BSP agreement, prequalified unit or group, production market credential, exercised activation, settlement statement or customer payout evidence was found on enterprise/main. No Nordic-country-specific operation is present in the curated public OpenAPI contract.

Carbon

Operational carbon estimates must identify the bidding zone, time interval, factor source and whether the value is marginal or average. They are not carbon credits. No Nordic carbon-credit methodology, verifier, registry or buyer is activated for AmpVerve.

Evidence

• Energinet ancillary-services tender conditions, checked 2026-08-20
• Fingrid reserve markets, checked 2026-08-20
• Fingrid independent aggregation, checked 2026-08-20
• Statnett reserve markets, checked 2026-08-20
• Svenska kraftnat balancing market, checked 2026-08-20

Open activation gates

• choose country, bidding zone, product and contractual BSP route;
• obtain national TSO agreements and prequalify the exact resource group;
• map resources to DSO, meter, BRP and product-specific aggregation rules;
• implement and test bidding, activation, acknowledgement, cancellation and telemetry;
• validate capacity and energy settlement separately and exercise payout in DKK, EUR, NOK or SEK;
• document stacking and primacy across local, national, Nordic and European products.

NZ: New Zealand

Readiness

Capability separation

Official market routes

The Electricity Authority describes three wholesale demand-side mechanisms: dispatchable demand, dispatch notification and difference bids. Dispatchable demand is intended for large consumers above 10 MW and requires real-time telemetry and binding dispatch. Dispatch notification can serve loads above 1 MW and below 10 MW, including aggregated household resources, with monthly meter verification and the ability to decline a notification within the rules. Difference bids signal price sensitivity but do not receive dispatch or revenue.

Participation requires the relevant industry role or agent, an approved dispatch-capable station, acceptable metering and access to the Wholesale Information and Trading System. A public spot price feed alone does not satisfy these gates.

AmpVerve activation state

The mobile application contains New Zealand locale, NZD and manufacturer catalogue metadata. No market participant or agent agreement, approved load station, WITS production credential, dispatch integration, settlement statement or customer payout evidence was found on enterprise/main. No New Zealand-specific operation is present in the curated public OpenAPI contract.

Carbon

The New Zealand Emissions Trading Scheme creates NZUs for activities covered by its rules. It does not automatically issue units for a household smart-charging estimate. AmpVerve needs a verified eligible method, legal rights, monitoring, registry controls and a buyer before carbon monetisation can be enabled.

Evidence

• Electricity Authority demand-side participation, checked 2026-08-20
• Electricity Authority WITS, checked 2026-08-20
• Electricity Authority real-time dispatch and pricing, checked 2026-08-20
• Ministry for the Environment NZ ETS overview, checked 2026-08-20

Open activation gates

• choose dispatchable demand, dispatch notification or a retail-only route;
• secure participant or agent status and System Operator approval;
• integrate WITS, dispatch messaging, acknowledgements and withdrawal states;
• validate meter, GXP, baseline and monthly verification processes;
• reconcile clearing or partner statements and exercise NZD payout;
• complete Privacy Act, consent, retention and data-location review.

Security

• Tenant isolation. Every request is scoped to the organisation in the credential, never to a client supplied parameter. A conflicting X-Tenant-ID header is refused with 403.
• API keys are stored only as an HMAC-SHA256 under a server secret and are shown once. Webhook signing secrets are stored encrypted and shown once.
• Webhook targets must be public HTTPS hosts; the address is checked again before every delivery and redirects are not followed.
• Vendor credentials you supply for device integrations are never echoed back in a response.

Report a vulnerability to security@ampverve.com. Please never test against another organisation's data. See also the security overview.

Support

Check the status page before reporting an outage. A component with no recent health check shows as not observed rather than operational, and incidents are shown to signed in organisations in the console.

What to include in a report

• Your organisation identifier and the affected site_id or asset_id.
• The exact request: method, full path and headers with the credential removed.
• The full response body and status code, with UTC timestamps.
• The output of GET /api/telemetry/readyz at the time.

This page renders its API reference from the live specification at app.ampverve.com/api-docs/openapi.json. If an operation does not respond as described, report it to api@ampverve.com.