Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.amps.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Amps API exposes three layers: one verb-set, one parameter shape, one error envelope, across every device with an API. Hardware-level commands stay imperative. Intent-level commands declare a goal. A higher routing layer for cross-device dispatch is forthcoming.

​
The three layers

LayerSurfaceWhat you control
Device Controlcharge, discharge, idleExactly what the device does. Time windows, parameters, OEM-side commitment.
Strategyauto.balanced, auto.reserve, auto.exportA goal. The device or Amps picks how to deliver it.
IntelligenceCross-device routing (forthcoming)A higher-level objective. Amps picks which device to dispatch.
The layers share the same commands map, the same Quantity parameters, and the same lifecycle. Integrate once against the unified API and you move up the stack without rewriting anything.

​
Device Control: imperative

charge, discharge, and idle are direct imperatives. You say exactly what should happen, Amps translates that to the OEM’s native call, and the action records what got committed. 
{
  "action": {
    "command": "charge",
    "parameters": {
      "power": { "value": 5, "unit": "kw" },
      "target": { "value": 90, "unit": "percent" }
    },
    "start": "2026-06-01T00:30:00+01:00",
    "end":   "2026-06-01T05:30:00+01:00"
  }
}
Amps decides how to express the command on the wire, not whether to run it. The same request shape works against every supported device. You never need to know which OEM is on the other end. Every state transition is recorded. Every result fires a webhook. If the OEM rejects, the action transitions to failed and Amps does not retry.

​
Strategy: intent

auto.balanced, auto.reserve, and auto.export declare a goal:
CommandIntent
auto.balancedOptimise for self-consumption. Match generation to load.
auto.reserveReserve capacity for grid outage. Stay above the reserve floor.
auto.exportMaximise grid export. Discharge when the export tariff is attractive.
Each auto command names a self-managing mode at intent level. auto.balanced maps to the device’s self-consumption mode, auto.reserve to its backup mode, auto.export to its grid-export mode. The same intent landing on a different device returns the same command in the device’s commands map. See canonical actions for the full mapping.

​
Intelligence: routing (forthcoming)

Capability-driven dispatch is forthcoming. Above the device layer, a multi-device action expressed once will apply to any device that exposes the right capability.

​
Brokerage, not VPP

Amps is a brokerage. It routes flexibility to the best execution venue across providers, never taking the position itself. There is no energy supply licence on the path, no proprietary trading desk. Think “Plaid for energy”, not “Octopus Energy on top of someone else’s hardware”. Every command flows through your own API key as your customer’s intent. Multi-tenant boundaries are absolute: a dispatch on behalf of one customer never reaches a device connected by another.

​
How devices are integrated

Errors come back as typed canonical codes (INVALID_CREDENTIALS, SCHEDULER_ACTIVE, RATE_LIMITED, DEVICE_OFFLINE); OEM-specific error names never reach you. What each device accepts is declared on the device itself and surfaced through capabilities. New devices graduate from sandbox-only simulations to general availability. The unified API does not change when a new OEM lands; the verb-set and the response shapes stay the same.

​
Supported devices

Five DER categories share the same contract. The verbs and parameter shapes are identical across categories; what each device exposes depends on its capabilities.
  • Batteries. Read charge level, capacity, and energy flow. Push charge, discharge, idle, auto.balanced, auto.reserve, auto.export. Common use cases: home energy storage management, peak shaving and load shifting, backup power coordination, solar self-consumption optimisation.
  • EV chargers. Read charging status, power, and session totals. Push start, stop, and scheduled charging. Common use cases: fleet charging management, public charging network operations, home charging optimisation, demand response programs.
  • HVAC systems. Read current temperature and mode. Push setpoint and mode changes (auto, heat, cool, off). Common use cases: smart home automation, demand response load reduction, energy efficiency optimisation, comfort management.
  • Solar inverters. Read real-time power production and energy totals (daily, monthly, lifetime). Read-only on most OEMs. Common use cases: solar production monitoring, energy management dashboards, ROI tracking and reporting, grid integration coordination.
  • Vehicles. Read battery level, range, charging status, and capacity. Push charge limits and start/stop where the OEM allows. Common use cases: fleet management and tracking, charging optimisation, range planning, vehicle-to-grid (V2G) applications.

​
Sync reads, async writes

Reads and writes share the same auth and access path, then split. A pull is synchronous: the API returns device state in the HTTP response, falling back to the last-known stored state on a transient OEM-side failure. A push is asynchronous: the API returns 202 with an actionId, dispatch happens in the background, and the result lands via webhook or polling. The async tail keeps response latency decoupled from OEM round-trips. State updates and webhook delivery flow behind the API, so a slow OEM never holds your request open. See device state for cache semantics and webhooks for delivery.

​
Frequently asked questions

​
What is the difference between a push action and a schedule?

A push targets a single device with one body and runs immediately, at a future instant, or across a window. A schedule groups pushes into slots and a recurrence pattern. Schedules sit on top of the push primitive; the push is the only thing that ever fires against an OEM. The schedule resource manages slot definitions, recurrence, DST, and lifecycle.

​
Why does Amps have separate auto modes per OEM?

Amps does not. The unified API declares three shared auto modes (auto.balanced, auto.reserve, auto.export) that every battery speaks. The client sends the same request shape regardless of which OEM is on the other end.

​
Is Amps a VPP?

Amps is a brokerage, not a VPP. The platform routes flexibility to the best execution venue across providers; it does not take energy positions itself. There is no energy supply licence on the path, no proprietary trading desk. Every command flows through the customer’s own API key. Multi-tenant boundaries are absolute. Think “Plaid for energy”, not “Octopus Energy on top of someone else’s hardware”.

​
How does Amps support a new OEM?

New devices graduate from sandbox-only simulations to general availability. What each device accepts is declared on the device itself, surfaced via capabilities. The unified API does not change when a new OEM lands; clients pick up the new device automatically once it reaches their tier.

What to expect

Why the surface looks the way it does.

Canonical Actions

The single body shape every push uses.

Capabilities

Per-device declaration of supported commands and parameters.

Auth Model

API keys, sandbox vs live, the Auth Journey.