The mental model

Four nouns. Learn these and the rest of the API follows.

You register assets against sites, then stream records against assets. Everything else in this API either reads that data back, or enriches it with market and grid signals.

Status labels are part of the contract

Every endpoint on this page carries a label. Treat it as binding.

First call in three steps

From nothing to a durable, verified write.

1. Confirm the platform is up

   No credential needed. This is also the endpoint you will poll in production to detect degradation.

   curlCopy

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

   ResponseCopy

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

2. Get a token

   Returns a 60 minute access token and a 7 day refresh token. Cache the access token. Do not call this per request; it is rate limited to 5 per minute per IP.

   curlPythonNodeCopy

   curl -X POST https://app.ampverve.com/api/auth/login \
     -H 'content-type: application/json' \
     -d '{"email":"you@partner.com","password":"..."}'

   import os, requests
   
   BASE = "https://app.ampverve.com"
   
   r = requests.post(
       f"{BASE}/api/auth/login",
       json={"email": os.environ["AMPVERVE_EMAIL"],
             "password": os.environ["AMPVERVE_PASSWORD"]},
       timeout=30,
   )
   r.raise_for_status()
   token = r.json()["access_token"]
   auth = {"Authorization": f"Bearer {token}"}

   const BASE = "https://app.ampverve.com";
   
   const res = await fetch(`${BASE}/api/auth/login`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       email: process.env.AMPVERVE_EMAIL,
       password: process.env.AMPVERVE_PASSWORD,
     }),
   });
   if (!res.ok) throw new Error(`login failed: ${res.status}`);
   const { access_token } = await res.json();

3. Write telemetry, and verify it landed

   Send an array. Then check two things in the response: that stored equals count, and that anomalies is empty.

   curlPythonNodeCopy

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

   batch = [
       {"asset_id": "site-0412-inverter-1",
        "ts": "2026-07-31T14:00:00Z",
        "power_kw": -4.812, "voltage": 241.3,
        "status": "producing"},
       {"asset_id": "site-0412-battery-1",
        "ts": "2026-07-31T14:00:00Z",
        "power_kw": 2.4, "soc_pct": 68.5,
        "status": "charging"},
   ]
   
   r = requests.post(f"{BASE}/api/telemetry/ingest",
                     headers=auth, json=batch, timeout=60)
   r.raise_for_status()
   out = r.json()
   
   # 200 does not mean persisted. Check both.
   if out["stored"] != out["count"]:
       raise RuntimeError(f"not persisted: {out}")
   if out["anomalies"]:
       log.warning("quality flags: %s", out["anomalies"])

   const batch = [
     { asset_id: "site-0412-inverter-1",
       ts: "2026-07-31T14:00:00Z",
       power_kw: -4.812, voltage: 241.3,
       status: "producing" },
   ];
   
   const r = await fetch(`${BASE}/api/telemetry/ingest`, {
     method: "POST",
     headers: {
       authorization: `Bearer ${access_token}`,
       "content-type": "application/json",
     },
     body: JSON.stringify(batch),
   });
   const out = await r.json();
   
   // 200 does not mean persisted. Check both.
   if (out.stored !== out.count) throw new Error("not persisted");
   if (out.anomalies.length) console.warn(out.anomalies);

   ResponseCopy

   { "count": 2, "stored": 2, "streamed": 2, "anomalies": [] }

   Confirm independently with GET /api/telemetry/live/events?limit=5. You are integrated.

Bearer tokens

One scheme. Every request carries an Authorization header, and every request is scoped to the organisation inside the token.

Roles, not scopes

There is no OAuth scope model. Authorisation is by role, carried on the token.

A machine to machine ingestion integration should use a dedicated user with OPERATOR. Do not share a human's credentials with a service.

Tenant isolation

The organisation is taken from the token, never from a parameter you control. If you send an X-Tenant-ID header that disagrees with the token, the request is rejected with 403 Tenant mismatch. There is no way to read another organisation's data with your token.

Handling expiry

Refresh proactively at roughly 80 percent of the token lifetime, and treat a 401 as a signal to refresh once and retry once. Do not retry a 401 in a loop; you will hit the authentication rate limit and lock yourself out for 15 minutes.

class AmpVerve:
    def __init__(self, email, password, base="https://app.ampverve.com"):
        self.base, self._email, self._pw = base, email, password
        self._token, self._exp = None, 0

    def _headers(self):
        # refresh at 80% of the 60 minute lifetime
        if time.time() > self._exp - 720:
            r = requests.post(f"{self.base}/api/auth/login",
                              json={"email": self._email,
                                    "password": self._pw}, timeout=30)
            r.raise_for_status()
            self._token = r.json()["access_token"]
            self._exp = time.time() + 3600
        return {"Authorization": f"Bearer {self._token}"}

API keys Planned

A long lived, organisation scoped X-API-Key is the right credential for server to server ingestion. It is not available yet.

Where to point your client

Testing without a sandbox

Until an isolated sandbox exists, AmpVerve provisions a dedicated non-production organisation on production infrastructure. It is a real tenant with real isolation, and it is the only supported way to test writes.

• Ask support for a non-production organisation. You get separate credentials and a separate tenant_id.
• Prefix your asset identifiers so test data is obvious, for example test-site-0001-inverter-1.
• Never write test data into a production organisation. Credential and data writes that look like placeholders are rejected at the service layer against real tenants.
• Read only endpoints, such as market data and carbon intensity, are safe to exercise from any environment.

Getting access

Access is granted per organisation under an integration agreement. Email api@ampverve.com with your organisation name, the environments you need, and the roles your integration requires. You receive credentials for a dedicated integration user, not a shared login.

Getting data in

This is the surface most integrations spend their time on. Read this section fully before writing a client. The behaviours below are not incidental; they change how you should design retries, deduplication and alerting.

Telemetry schema and units

Fields AmpVerve recognises are mapped onto canonical, indexed columns. Everything else is preserved in a raw JSON column and stays queryable. You do not need to strip your native payload down before sending it, but only canonical fields are aggregated and surfaced by the read endpoints.

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 $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "site_id": "site-0412",
    "type": "inverter",
    "name": "site-0412-inverter-1",
    "details": {"vendor":"SolarEdge","rated_kw":7.6,"serial":"7E1F-22B9"}
  }'

Identifier rules

• site_id is yours. Free form string. Use your own stable site key so your systems and AmpVerve agree without a translation table.
• asset_id must be globally 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 physical hardware. History is keyed on it. Replacing an inverter means a new asset id and a new registry entry.
• Keep it stable across firmware and vendor portal changes. If your upstream serial changes, keep your asset_id and record the serial in details.

Timestamps and timezones

ts is client supplied and is the sole basis for bucketing, ordering and every query in this API. Get it wrong and the data is unusable in a way that is hard to spot.

• Store and send UTC. Convert at the edge of your system, not in the middle of it.
• British Summer Time is a real hazard. UK sites shift by an hour twice a year. If you derive ts from a vendor portal that reports local wall clock time, the autumn transition produces a duplicated hour and the spring transition a missing one. Convert vendor local time to UTC using a timezone database, never by adding a fixed offset.
• Timestamps are not deduplicated. Two records with the same asset_id and ts both persist. See idempotency below.
• Sub second precision is preserved but AmpVerve buckets to a minimum of 5 minutes on read.

Batching and backfill

Batching

• Send an array. A batch is written in one database transaction, so it is atomic: every row lands or none do.
• Recommended batch size is 100 to 1000 records. Below 100 you pay per request overhead; above a few thousand you increase the blast radius of a single failed transaction.
• There is no server enforced record cap today. The practical ceiling is request body size. Treat 5 MB as a safe upper bound.
• Prefer one batch per site per interval. It keeps failure attribution simple, which is exactly what you want when a single site starts misbehaving.

Backfill

Backfill is the same call with older timestamps. Two constraints apply.

Idempotency, deduplication, ordering

What this means for retries

On a timeout or a 5xx, you do not know whether the write landed. There are two correct strategies. Pick one and be consistent.

def ingest_with_verification(client, batch, attempts=4):
    """Retry safely without risking duplicate rows."""
    key = (batch[0]["asset_id"], batch[0]["ts"])

    for attempt in range(attempts):
        try:
            out = client.post("/api/telemetry/ingest", json=batch).json()
        except (Timeout, ConnectionError):
            # Ambiguous. Verify before re-sending, never blind retry.
            if client.already_present(*key):
                return {"deduplicated": True}
            time.sleep(2 ** attempt)
            continue

        # 200 is not proof of persistence. Compare stored to count.
        if out["stored"] != out["count"]:
            time.sleep(2 ** attempt)
            continue

        return out

    raise IngestFailed("exhausted retries, data buffered locally")

Ordering

• Records within one batch are written in array order.
• Concurrent batches interleave. There is no cross batch ordering guarantee.
• The live event stream is ordered by arrival, not by ts.
• All read endpoints order by ts, so out of order arrival does not corrupt query results. Only the live tail reflects arrival order.

Idempotency keys Planned

The planned ingestion endpoint accepts an Idempotency-Key header, retained for 24 hours. Replaying a batch with the same key returns the original result without writing again, and deduplication on (site_id, asset_id, ts, metric) reports duplicate_discarded rather than silently double counting. Design your client to emit a stable key per batch now, and it becomes a one line change later.

Detecting bad and partial data

Three independent signals. A production integration watches all three.

1. The anomaly report, per record

Every ingest response includes an anomalies array, computed synchronously per record. A flagged record is still stored. Detection annotates, it never rejects.

{
  "count": 1, "stored": 1, "streamed": 1,
  "anomalies": [
    {
      "asset_id": "site-0412-battery-1",
      "reasons": ["soc_out_of_range", "power_out_of_range"],
      "record": { "soc_pct": 0.685, "power_kw": 2400 }
    }
  ]
}

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 and it is the same signal AmpVerve measures its uptime commitment against.

Reference consumer

def health_gate(base="https://app.ampverve.com"):
    """Return ('ok'|'degraded'|'down', detail). No auth required."""
    try:
        r = requests.get(f"{base}/api/telemetry/readyz", timeout=10)
    except Exception as exc:
        return "down", str(exc)

    body = r.json()
    checks = body.get("checks", {})

    if r.status_code == 503:
        return "down", checks

    # The subtle one: 200 and "ready", but nothing is persisting.
    if not checks.get("database"):
        return "degraded", "writes accepted but not persisted"

    return "ok", checks

Site level failure notification Planned

Today, detecting that one specific site has stopped reporting requires you to query telemetry and infer absence. Two planned capabilities close that gap:

• GET /api/telemetry/sites/{site_id}/health, returning last received timestamp, staleness, expected against observed record counts, completeness percentage, per asset health, and the open error codes for that site.
• Webhook events site.data.stale and ingest.batch.rejected, delivered with signature verification and retry, so failure reaches you rather than waiting to be polled for.

Both are specified below and neither is deployed. Until they ship, the readiness probe plus the persistence check plus your own per site staleness monitor is the supported pattern, and it is genuinely sufficient.

Authentication

Ingestion

Telemetry

Range and bucket

Asset type and metric

The pair selects both the source field and the unit. AmpVerve resolves the metric across several field names, including fields nested inside the preserved raw object, so a series still resolves when your payload used a vendor native name. A source field ending in _w is divided by 1000 and returned in kW.

curl -H "authorization: Bearer $TOKEN" \
  "https://app.ampverve.com/api/telemetry/assets/solar/site-0412-inverter-1/history?range=hourly"

{
  "asset_id": "site-0412-inverter-1",
  "asset_type": "solar",
  "metric": "generation",
  "range": "hourly",
  "unit": "kW",
  "series": [
    { "t": "2026-07-31T13:00:00+00:00", "v": -4.907 },
    { "t": "2026-07-31T14:00:00+00:00", "v": -5.104 }
  ],
  "summary": { "count": 36, "min": -5.42, "max": -0.11,
                "avg": -3.918, "latest": -5.104 },
  "source": "timeseries"
}

Registry

Market data

Live UK electricity price, wholesale and carbon signals. Sourced from Octopus Energy, Elexon BMRS and National Grid ESO.

Flexibility

Distribution network flexibility, via UKPN LocalFlex and SSEN ElectronConnect. All three endpoints return 503 if AmpVerve's credentials for the requested platform are not configured for your environment.

curl -X POST https://app.ampverve.com/api/vpp/flex/offers \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "dno": "SSEN",
    "reserve_object_id": "RO-88213",
    "tender_platform_id": "TND-2026-0731-01",
    "direction_turn_up": false,
    "intervals": [{
      "start_utc": "2026-08-01T17:00:00Z",
      "duration_minutes": 120,
      "price_gbp_per_mwh": 185.0,
      "capacity_mw": 0.45
    }]
  }'

Certificates

Platform

Error catalogue

Every error you can currently receive, what it means, and what to do about it.

The error body today

{ "detail": "Authorization header missing" }

// detail is an ARRAY here, not a string. Parse accordingly.
{
  "detail": [
    { "type": "missing", "loc": ["body", "email"],
      "msg": "Field required", "input": {} }
  ]
}

// The one endpoint with a machine readable code today.
{
  "detail": {
    "error": "plan_limit_exceeded",
    "metric": "api_calls",
    "limit": 100000,
    "upgrade_url": "/billing/upgrade"
  }
}

Live error catalogue

Site level coded errors Planned

The committed target is a stable machine readable envelope carrying a code, the site and asset it concerns, and an explicit remediation action, returned per record so a partial failure is actionable without human triage.

{
  "error": {
    "code": "AV-4104",
    "message": "Unknown asset_id for site",
    "site_id": "site-0412",
    "asset_id": "inverter-9",
    "action": "Register the asset via POST /api/twin/ or correct asset_id.",
    "doc_url": "https://www.ampverve.com/api-docs/#errors",
    "request_id": "req_01J9X7QK3M",
    "retryable": false
  }
}

Webhooks

Event catalogue Planned

Payload Planned

{
  "id": "evt_01J9X7QK3MZ2",
  "type": "site.data.stale",
  "created_at": "2026-07-31T14:35:02Z",
  "organisation_id": "org_7f21",
  "api_version": "2026-07-31",
  "data": {
    "site_id": "site-0412",
    "code": "AV-5301",
    "last_received_at": "2026-07-31T14:05:00Z",
    "staleness_seconds": 1802,
    "expected_interval_seconds": 300,
    "assets_silent": ["site-0412-battery-1"]
  }
}

Signature verification Planned

Every delivery will carry X-AmpVerve-Signature: t=<unix>,v1=<base64>, an HMAC-SHA256 over "<t>.<raw body>". This is the same scheme AmpVerve already operates in production for inbound DNO dispatch, so it is proven rather than theoretical.

• Compute the HMAC over the raw request body, before any JSON parsing. Re-serialising changes the bytes and the signature will not match.
• Compare in constant time. A naive string comparison leaks timing.
• Reject a timestamp more than 300 seconds from now, to prevent replay.
• Multiple v1= values may appear during secret rotation. Accept the delivery if any matches.

import base64, hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tol=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts = parts.get("t", "")

    # Reject replays before doing any crypto.
    if not ts.isdigit() or abs(time.time() - int(ts)) > tol:
        return False

    signed = f"{ts}.".encode() + raw_body
    expected = base64.b64encode(
        hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    ).decode()

    # Any v1 may match during secret rotation. Constant time compare.
    return any(
        hmac.compare_digest(expected, candidate)
        for key, candidate in
        (p.split("=", 1) for p in header.split(","))
        if key == "v1"
    )

import crypto from "node:crypto";

export function verify(rawBody, header, secret, tol = 300) {
  const parts = new Map(header.split(",").map((p) => p.split("=")));
  const ts = parts.get("t");

  // Reject replays before doing any crypto.
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > tol) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(`${ts}.`), rawBody]))
    .digest("base64");

  return header
    .split(",")
    .filter((p) => p.startsWith("v1="))
    .some((p) =>
      crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(p.slice(3)),
      ),
    );
}

Retry, backoff and replay Planned

Rate limits

• Exceeding a limit returns 429 with Retry-After in seconds. Honour it.
• Batch rather than parallelise. One request carrying 500 records costs one unit against the limit; 500 single record requests cost 500. This is the entire reason batching exists.
• Back off exponentially with jitter. Synchronised retries across your fleet turn one blip into a self inflicted outage.
• Higher ingestion limits are available under an integration agreement. Tell support your expected sites, assets per site and reporting interval, and a limit is set for you.

Pagination

Pagination is not uniform across the API yet. Check per endpoint rather than assuming.

Cursor pagination with a stable next_cursor is Planned for every list endpoint, and will be introduced additively so existing clients keep working.

Versioning and deprecation

The API is date versioned. The current version is 2026-07-31, and it is the info.version of the OpenAPI document.

What can change without a new version

• A new endpoint.
• A new optional request field.
• A new field in a response object.
• A new enum value in a field documented as extensible, such as an anomaly reason.

Your client must tolerate all four. Ignore unknown response fields rather than failing on them, and never assume an enum is closed unless this page says it is.

What requires a new version

• Removing or renaming a field.
• Changing a field's type, unit or sign convention.
• Making an optional request field required.
• Changing the status code for an existing condition.
• Removing an endpoint.

Deprecation policy

Endpoints marked Beta are excluded from this policy and may change with 30 days notice. Endpoints marked Planned carry no commitment until they ship.

Reliability and service levels

The ingestion layer design target, how it is defined, and what is and is not measured today.

What counts as available

This is the definition AmpVerve is building toward. It is not yet instrumented, so no availability figure is claimed. A one minute bucket would be available when both hold:

1. GET /api/telemetry/readyz returns 200 with status: "ready".
2. A well formed authenticated POST /api/telemetry/ingest returns 2xx with stored equal to count.

Both conditions are required. The second exists deliberately: a response that returns 200 while stored is 0 is not an available minute, because the data did not persist. Availability here means data landed, not that a request completed.

Quarterly availability would be available minutes divided by eligible minutes, expressed as a percentage. No such measurement runs today. The second condition in particular requires an authenticated write probe that AmpVerve does not yet operate, and readyz alone does not distinguish every degraded state. Any availability number quoted before that instrumentation exists would be unsourced, so AmpVerve does not quote one. Enterprise availability terms are agreed in the contract, not on this page.

What is excluded

Service credits

AmpVerve does not publish a service credit schedule, because a credit schedule is only meaningful once achieved availability is measured, and it is not measured today. Availability terms, including any credits, are agreed per contract. Ask during commercial discussion and you will get the current position in writing rather than a number this page cannot stand behind.

How degradation is signalled

Recommended consumer posture

1. Buffer locally. Hold at least 24 hours of un-acknowledged telemetry on disk. Availability targets are not a substitute for a buffer.
2. Never treat 200 as durability. Acknowledge from your buffer only when stored equals count.
3. Alert on the readiness probe, not only on your own request failures. It gives you minutes of warning.
4. Replay in timestamp order after an outage, oldest first, throttled to a few batches per second.
5. Monitor per site staleness yourself until the site health endpoint ships. A site that stops reporting produces no errors at all, only an absence.

Security and data handling

Transport

• TLS 1.2 or above required. Plain HTTP is not served.
• HSTS is enforced with a one year max age including subdomains.
• Charge point connections use OCPP security profiles 1 through 3, including mutual TLS with client certificates on the dedicated endpoint.
• Inbound DNO dispatch is authenticated by HMAC-SHA256 with a 300 second replay window and constant time comparison.

Tenant isolation

• Every query is scoped by organisation, taken from the token and never from a client supplied parameter.
• A conflicting X-Tenant-ID header is rejected with 403 rather than silently ignored.
• Cross tenant data exposure is treated as a P0 incident with immediate notification to every affected organisation.

Credentials

• Passwords are hashed with bcrypt. They are never stored or logged in a recoverable form.
• Vendor credentials you supply for device integrations are redacted on every response path. They are never echoed back.
• Platform secrets live in Azure Key Vault and are surfaced to workloads as Kubernetes secrets. They are never in source control.
• Refresh tokens are tracked by identifier and revoked immediately on logout.

Data handling and retention

• Data is processed and stored in the UK and EU. It is not transferred outside without a documented safeguard.
• Export and erasure requests are handled per the data processing agreement. Erasure covers personal data; aggregate settlement records may be retained where a regulatory obligation requires it.

Reporting a vulnerability

Email security@ampverve.com. Acknowledgement within 1 business day, triage within 3. Please do not test against another organisation's data under any circumstances.

See also the security overview and the data processing agreement.

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

https://api.ampverve.com and https://sandbox.ampverve.com are planned and do not resolve as of 2026-08-20. Do not place them in a client configuration. See ../ENVIRONMENT_ACTIVATION.md for the activation sequence.

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 current credential is a bearer JWT obtained with email and password. API key authentication, OAuth client credentials and delegated end user tokens are planned. Keys returned by /api/devtools/apikeys are not accepted as credentials today.

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.

Planned discovery endpoint

GET /api/platform/v1/capabilities is planned and returns 404 today. Its planned OpenAPI contract is included in ../openapi.yaml so partners can design an honest availability UI before the route is released.

The endpoint accepts any valid ISO country code. Unknown or unverified coverage returns an explicit unavailable result. It must never fall back to GB or infer market access from locale.

{
  "country_code": "US",
  "subdivision_code": "US-CA",
  "evaluated_at": "2026-08-20T16:30:00Z",
  "evidence_version": "2026-08-20",
  "capabilities": [
    {
      "name": "asset.telemetry",
      "state": "connection_available",
      "asset_types": ["ev", "charger", "battery"],
      "requirements": ["compatible provider account", "customer consent"]
    },
    {
      "name": "flex.revenue",
      "state": "partner_gated",
      "partner": "Leap",
      "requirements": [
        "technical connector merged and deployed",
        "eligible programme and utility territory",
        "meter or device enrolment",
        "dispatch and telemetry verification",
        "settlement and payout activation"
      ]
    }
  ]
}

This example describes the shape and prerequisite chain. It does not claim the planned endpoint or US revenue path is live.

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. The planned ingestion v1 contract retains an Idempotency-Key for 24 hours.

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

Current pagination is not uniform. Some lists return the complete set, some use limit, and some use page and page_size. Check each operation.

The planned standard is cursor pagination:

{
  "data": [],
  "page": {
    "next_cursor": "opaque",
    "has_more": true
  }
}

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

POST /api/devtools/webhooks currently stores registrations only. AmpVerve does not deliver events from this route as of the OpenAPI evidence date. Do not deploy a workflow that depends on it.

The planned delivery contract includes:

• 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.

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. Before publishing an official SDK, 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, generated clients are partner-owned artifacts. Do not publish package installation commands 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 beta endpoints.

Service levels and status

/api/telemetry/readyz is the current machine-readable ingestion readiness signal. A public multi-component status page is planned. 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, wholesale, carbon and DNO region 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/trading/prices/wholesale, beta;
• GET /api/trading/grid/dno-region, live;
• GET /api/vpp/flex/tenders, partner-gated;
• GET /api/vpp/flex/contracts, partner-gated;
• POST /api/vpp/flex/offers, partner-gated.

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.

Changelog

2026-07-31 Current

• First published OpenAPI 3.1 specification, generated from the deployed services rather than hand written.
• Every endpoint labelled Live, Beta or Planned, verified against production.
• Complete error catalogue with remediation actions.
• Ingestion documented in depth: canonical schema, sign convention, timezone handling, batching, backfill, idempotency, ordering, and the three degradation signals.
• Uptime commitment defined with an explicit measurement method and a service credit schedule.
• Webhook contract specified in full and clearly marked as not yet delivered.
• Correction. A previous revision of this page documented base URLs and endpoints that do not exist, including api.ampverve.com, a sandbox host, and client SDK packages. None of them were live. They have been removed and replaced with the verified surface. If you built against that revision, contact support and it will be corrected with you directly.

Support

What to include in an incident report

This turns a day of back and forth into an hour.

• Your organisation identifier and the affected site_id or asset_id.
• The exact request: method, full path, and headers with the token redacted.
• The full response body and status code.
• Timestamps in UTC, with the window over which it occurred.
• The output of GET /api/telemetry/readyz taken at the time.
• Whether stored matched count on the failing requests.

This documentation describes the AmpVerve Platform API as deployed on 2026-07-31. Every endpoint marked Live was verified by an actual request. If you find one that does not respond as described, report it to api@ampverve.com and it will be corrected, because a partner is building against it.