Battery Cheat Sheet

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.

Quick reference for the canonical Amps battery surface. The first three sections (modes, parameters, settings) are battery-specific. Lifecycle, conflict resolution, environments, errors, and MCP terms apply across every device type. Every term matches the OpenAPI spec at /openapi/openapi.json. Agents that hallucinate selfconsumption or gridcharge are running over a partial view of the canonical surface. Pasting this page into the system prompt, or wiring the MCP server, is the cheapest way to ground them in the same vocabulary the API enforces.

​

Modes

The canonical battery surface exposes six command modes. Direct modes are explicit imperatives. Auto modes declare intent and let the device or Amps pick the implementation. charge Direct imperative. Charge from grid or solar, optionally bounded by target and power. Defined on canonical actions. discharge Direct imperative. Discharge to load or grid, optionally bounded by target and power. Defined on canonical actions. idle Pause charge and discharge. Battery sits. auto.balanced Optimise for self-consumption. Charge when solar is plentiful, discharge when the home needs it. auto.reserve Reserve capacity for grid outage protection. Stay charged above the reserve floor. auto.export Maximise grid export. Discharge when the export tariff is attractive. A mode’s presence in a device’s commands map means supported. Absence means rejected. There is no supported: boolean field.

​

Parameters

Every numeric parameter on a push is a Quantity. target Upper state-of-charge limit on charge; lower state-of-charge limit on discharge. Unit: percent. power Rate cap. The battery will not draw or deliver power faster than this rate. Unit: kw. reserve Reserve floor preserved while the mode is active. Acts as a second safety boundary distinct from device-wide settings. Unit: percent. Quantity Self-describing numeric value with its unit: { value, unit }. The unit travels with the value, so 80 is never ambiguous between percent, kilowatts, or amps.

​

Lifecycle

Every action moves through a small state machine. Subscribe to push.completed and push.failed via webhooks, or poll the action endpoint. scheduled Persisted, queued to fire at start. Initial state for any push that carries start. acknowledged The platform has dispatched the command to the OEM and the OEM accepted it. Initial state for an immediate push (no start). completed Terminal. The OEM API returned success. Amps does not poll the device to verify end-state; the next pull reflects reality. failed Terminal. The OEM rejected the command, or a transient failure exhausted retries. No automatic retry: commands are time-sensitive. cancelled Terminal. POST /actions/{id}/cancel was called before dispatch. Push action A single canonical body sent to a device push endpoint. The only execution primitive. Schedules, recurrence, and slots all coordinate pushes; nothing else dispatches commands.

​

Scheduling

Defined in full on scheduling. Slot A template inside a schedule. Two variants: at (absolute ISO 8601 timestamp) and time (wall-clock HH:mm plus a schedule-level timezone). A schedule cannot mix variants in one payload. Recurrence A schedule’s recurrence rule. Expands into slot instances on a rolling horizon (default 7 days, bounded 1-30). A daily cron tops up the horizon. Supported types include daily, weekly, and weekday filters. Exclusion A weekday or date range filtered out of recurrence expansion. Excluded instances are silently omitted; no schedule.slot_skipped webhook fires.

​

Conflict resolution

Only one non-terminal action can target a device at a time. When a new push collides with an active or scheduled action, onConflict decides what happens. onConflict Property on the push request body that names the resolution strategy. Omit to receive 409 with the conflicting action ID. cancel_and_replace Cancel the conflicting action, run the new one. queue_after Defer the new action’s start to the conflict’s end.

​

Settings

Defined in full on the canonical battery settings surface. Settings are persistent, non-conflicting, and fire-and-forget. They run through POST /battery/{deviceId}/settings. The litmus test against an action: “does this make sense with a time window?” If no, it is a setting. Numeric settings ride on Quantity. Each value carries its unit explicitly. safety_reserve The lowest state-of-charge the battery will ever reach, even during a power cut. Unit: percent. Range: 0-100. discharge_floor The lowest state-of-charge the battery will reach during normal operation. Unit: percent. Range: 0-100. charge_ceiling The highest state-of-charge the battery will charge to. Unit: percent. Range: 0-100. export_limit Maximum power the battery can send back to the grid. Unit: watts. Min: 0. max_charge_rate Maximum rate the battery will charge at. Unit: amps. Min: 0. max_discharge_rate Maximum rate the battery will discharge at. Unit: amps. Min: 0. scheduler_enabled Whether the device’s native scheduler is active. Auto-managed by the platform when a schedule is set or cleared. Read-only; rejected on writes with READ_ONLY_SETTING.

​

Capabilities

Capability response The body returned by GET /battery/{deviceId} (and equivalents for other device types). Carries state, commands, and settings. The vocabulary you read is the vocabulary you write back. Presence in the commands map means supported. Absence means rejected.

​

Onboarding

Link UI Hosted authentication flow at https://auth.amps.ai/{appId}. End users select an OEM, enter credentials, complete MFA if the OEM requires it, pick devices, and grant consent. Defined on Link UI > Getting started. Linked account An end user’s authenticated session with an OEM, captured during Link UI. One linked account can expose multiple devices. Consent revocation A user-initiated removal of an Amps app’s access to a linked account. Downstream device access is revoked, and the linked devices are marked unavailable on the next pull.

​

Environments

sandbox Simulated-device environment. No real OEM calls. Realistic device simulations driven by UTC time patterns. API keys carry an explicit sandbox flag. live Real-OEM environment. Pushes hit physical devices and change their state. Treat live calls deliberately. Defined on environments.

​

Errors

Error envelope The shape of every rejection: { success: false, error: { code, message, details? }, meta }. The success counterpart is { success: true, data, meta }. Read body.error.code, never raw top-level fields. Common canonical error codes include UNSUPPORTED_PARAMETER, UNSUPPORTED_UNIT, EXECUTION_NOT_SUPPORTED, MODE_OVERRIDDEN, SCHEDULER_ACTIVE, VPP_LOCKED, and START_OUT_OF_RANGE.

​

MCP

MCP server A service that exposes tools, resources, and prompts to AI agents over the Model Context Protocol. The Amps MCP server is hosted at https://docs.amps.ai/mcp and exposes two tools that read the docs and OpenAPI spec. See the Amps MCP overview. MCP client An AI tool that connects to MCP servers. Claude Desktop, Cursor, Windsurf, and Continue are MCP clients. Custom agents become MCP clients by speaking the JSON-RPC protocol. MCP tool A callable function an MCP server exposes. The Amps MCP server exposes two: search_amps_ai_documentation for ranked semantic snippets, and query_docs_filesystem_amps_ai_documentation for shell-style read-only access. See the tools reference.