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

# Battery Cheat Sheet

> Quick reference for the canonical Amps battery surface: modes, parameters, action lifecycle, conflict strategies, settings, environments, errors.

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](/concepts/canonical-actions).

**`discharge`** Direct imperative. Discharge to load or grid, optionally bounded by `target` and `power`. Defined on [canonical actions](/concepts/canonical-actions).

**`idle`** Pause charge and discharge. Battery sits.

**`auto.balance`** 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`](#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](/guides/webhooks/receive), or poll the action endpoint.

**`scheduled`** Persisted, waiting 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

Action-level deferral via `start` and `end` on push ships today, defined in full on [scheduling](/concepts/scheduling).

<Callout icon="clock" color="#ED6D2C">
  **Coming soon.** The `/schedules` resource and the primitives below.
</Callout>

**`Slot`** Will be 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 will not mix variants in one payload.

**`Recurrence`** Will be a schedule's recurrence rule that repeats a `time` slot day after day, for as long as the schedule stays active. Expected to support `daily`, `weekly`, and weekday filters.

**`Exclusion`** Will be a weekday or date range filtered out of recurrence expansion. Excluded instances will be silently omitted; no `schedule.slot_skipped` webhook will fire.

## 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`](#parameters). 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](/guides/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](/get-started/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`, `SCHEDULER_ACTIVE`, `VPP_LOCKED`, and `START_OUT_OF_RANGE`.

The full code taxonomy lives across two pages: [error envelope](/concepts/error-envelope) covers request-validation, conflict, and platform codes; [device error codes](/reference/error-codes) covers every code a device manufacturer can raise (auth, device, command, state conflict, transport).

## MCP

**`MCP server`** A service that exposes tools, resources, and prompts to AI agents over the Model Context Protocol. The Amps Documentation MCP server is hosted at `https://docs.amps.ai/mcp` and exposes two tools that read the docs and OpenAPI spec. See the [Working with agents overview](/ai-tools/overview) and the [Documentation MCP page](/ai-tools/mcp/documentation).

**`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](/ai-tools/mcp/tools).

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{__html: JSON.stringify({
"@context": "https://schema.org",
"@type": "DefinedTermSet",
"name": "Amps Battery Cheat Sheet",
"description": "Canonical Amps vocabulary: modes, parameters, action lifecycle, conflict strategies, settings, environments, error envelope, and MCP terms.",
"url": "https://docs.amps.ai/reference/battery-cheat-sheet"
})}}
/>