# Amps AI Documentation

## Docs

- [Confirmation gates](https://docs.amps.ai/ai-tools/building-agent-uis/confirmation-gates.md): Destructive tool calls (push, cancel) gate behind a UI confirmation. The agent proposes, the user clicks, the tool fires. Auditable, observable, not free-fire.
- [Dynamic UI rendering](https://docs.amps.ai/ai-tools/building-agent-uis/dynamic-ui-rendering.md): Pick UI primitives based on canonical envelope shape. Dumb components, props lifted from responses, one renderer covers every device family.
- [Self-describing responses](https://docs.amps.ai/ai-tools/building-agent-uis/self-describing-responses.md): Every Amps response carries the contract for the next request. Capability introspection, typed Quantity envelopes, and 422s that return the device snapshot.
- [Documentation MCP](https://docs.amps.ai/ai-tools/mcp/documentation.md): Ground LLM agents in the Amps docs corpus. Hosted at docs.amps.ai/mcp. Two read-only tools: semantic search and shell-style filesystem query.
- [Examples](https://docs.amps.ai/ai-tools/mcp/examples.md): Agent workflows over the Amps MCP servers. Documentation MCP: write curl from a prompt, validate config, build a webhook handler. Execution MCP coming soon.
- [Execution MCP](https://docs.amps.ai/ai-tools/mcp/execution.md): Call the Amps API from any LLM agent. Distributed as @amps-ai/mcp on npm. Per-operation tools, helper tools, integrator-key auth with per-user identity. Coming soon.
- [Install](https://docs.amps.ai/ai-tools/mcp/install.md): Install the Documentation MCP or Execution MCP in Claude Desktop, Cursor, Windsurf, Continue, or any custom MCP client. One snippet per tool, plus a verify step.
- [Tool reference](https://docs.amps.ai/ai-tools/mcp/tools.md): Tools the Amps MCP servers expose. Documentation MCP: search and shell-style filesystem query. Execution MCP: per-operation API tools, coming soon.
- [Working with agents](https://docs.amps.ai/ai-tools/overview.md): Wire agents into Amps with two MCP servers. Ground them in the docs corpus. Drive UIs from self-describing API responses. Mixed-mode, agent-native.
- [Cancel a scheduled action](https://docs.amps.ai/api-reference/actions/cancel-a-scheduled-action.md): Cancel a deferred action that is still in `scheduled` state. Actions in any other state (`acknowledged`, `completed`, `failed`, `cancelled`) cannot be cancelled and return 409.
- [Get action status](https://docs.amps.ai/api-reference/actions/get-action-status.md): Retrieve the current state of any device action for polling. The action lifecycle progresses `scheduled` (deferred only) -> `acknowledged` -> `completed` | `failed`, with `cancelled` reachable from `scheduled`. The `deviceType` field discriminates the device family and the `command`/`parameters` sha…
- [List actions](https://docs.amps.ai/api-reference/actions/list-actions.md): Returns a paginated list of the actions the API key can access, across every device type, newest first. Each item is the same polymorphic action shape as `GET /actions/{actionId}`; the `deviceType` field discriminates the device family. Filter by `deviceId`, lifecycle `state`, device `type`, or end-…
- [Clear this battery's schedule](https://docs.amps.ai/api-reference/battery/clear-this-batterys-schedule.md): Clear the schedule set on this battery. The route is published ahead of the scheduler; every call returns 501 until it lands.
- [Get battery state](https://docs.amps.ai/api-reference/battery/get-battery-state.md): Retrieve the current state and capabilities of a battery device.
- [Get this battery's schedule](https://docs.amps.ai/api-reference/battery/get-this-batterys-schedule.md): Read the schedule currently set on this battery. A schedule is device config, so it is read on the device, the same surface that carries `settings`. The cross-device list lives at `GET /schedules`. The route is published ahead of the scheduler; every call returns 501 until it lands.
- [List battery devices](https://docs.amps.ai/api-reference/battery/list-battery-devices.md): Returns a paginated list of battery devices the API key can access, each with the last captured `state` and the canonical `commands` map. Live state is not pulled per call. Use `GET /battery/{deviceId}` for an authoritative read.
- [Push battery action](https://docs.amps.ai/api-reference/battery/push-battery-action.md): Send a command to a battery device. Immediate actions fire as soon as the platform dispatches them; deferred actions (with `start`) fire at the requested time. The action is processed asynchronously and a webhook is sent on completion.
- [Set this battery's schedule](https://docs.amps.ai/api-reference/battery/set-this-batterys-schedule.md): Set or replace the schedule on this battery. The schedule's contents are device config, so they are written on the device itself rather than posted to a separate resource. The body is a non-empty `slots` array (each slot an `at` absolute-timestamp variant or a `time` wall-clock variant), an optional…
- [Update battery device settings](https://docs.amps.ai/api-reference/battery/update-battery-device-settings.md): Write one or more writable settings on the device. Sparse: send only the settings you want to change. Read-only keys (e.g. `scheduler_enabled`) are rejected with 422 `READ_ONLY_SETTING`.
- [Clear this EV charger's schedule](https://docs.amps.ai/api-reference/ev-charger/clear-this-ev-chargers-schedule.md): Clear the schedule set on this EV charger. The route is published ahead of the scheduler; every call returns 501 until it lands.
- [Get EV Charger state](https://docs.amps.ai/api-reference/ev-charger/get-ev-charger-state.md): Retrieve the current state of an EV Charger device including charging status, power, and connection state
- [Get this EV charger's schedule](https://docs.amps.ai/api-reference/ev-charger/get-this-ev-chargers-schedule.md): Read the schedule currently set on this EV charger. A schedule is device config, so it is read on the device, the same surface that carries `settings`. The cross-device list lives at `GET /schedules`. The route is published ahead of the scheduler; every call returns 501 until it lands.
- [List EV Charger devices](https://docs.amps.ai/api-reference/ev-charger/list-ev-charger-devices.md): Get a paginated list of EV Charger devices with their last pull state
- [Push EV Charger action](https://docs.amps.ai/api-reference/ev-charger/push-ev-charger-action.md): Send a command to an EV Charger device. The action is processed asynchronously and a webhook is sent on completion.
- [Set this EV charger's schedule](https://docs.amps.ai/api-reference/ev-charger/set-this-ev-chargers-schedule.md): Set or replace the schedule on this EV charger. The schedule's contents are device config, so they are written on the device itself rather than posted to a separate resource. The body is a non-empty `slots` array (each slot an `at` absolute-timestamp variant or a `time` wall-clock variant), an optio…
- [Update EV Charger device settings](https://docs.amps.ai/api-reference/ev-charger/update-ev-charger-device-settings.md): Write one or more writable settings on the device. Sparse: send only the settings you want to change. Unknown or read-only keys are rejected with 422.
- [Clear this HVAC device's schedule](https://docs.amps.ai/api-reference/hvac/clear-this-hvac-devices-schedule.md): Clear the schedule set on this HVAC device. The route is published ahead of the scheduler; every call returns 501 until it lands.
- [Get HVAC state](https://docs.amps.ai/api-reference/hvac/get-hvac-state.md): Retrieve the current state of an HVAC device including mode, temperature, and humidity
- [Get this HVAC device's schedule](https://docs.amps.ai/api-reference/hvac/get-this-hvac-devices-schedule.md): Read the schedule currently set on this HVAC device. A schedule is device config, so it is read on the device. The cross-device list lives at `GET /schedules`. The route is published ahead of the scheduler; every call returns 501 until it lands. Following a schedule is available today via the `follo…
- [List HVAC devices](https://docs.amps.ai/api-reference/hvac/list-hvac-devices.md): Get a paginated list of HVAC devices with their last pull state
- [Push HVAC action](https://docs.amps.ai/api-reference/hvac/push-hvac-action.md): Send a command to an HVAC device. The action is processed asynchronously and a webhook is sent on completion.
- [Set this HVAC device's schedule](https://docs.amps.ai/api-reference/hvac/set-this-hvac-devices-schedule.md): Set or replace the schedule on this HVAC device. The schedule's contents are device config, so they are written on the device itself rather than posted to a separate resource. The body is a non-empty `slots` array (each slot an `at` absolute-timestamp variant or a `time` wall-clock variant), an opti…
- [Introduction](https://docs.amps.ai/api-reference/introduction.md): The Amps REST API: one contract across batteries, EV chargers, HVAC, solar inverters, and vehicles. Base URL, authentication, how the reference is organised, and the response envelope.
- [Get a schedule](https://docs.amps.ai/api-reference/schedules/get-a-schedule.md): Retrieve a single schedule by its handle, including its slots, recurrence, and current state. Use it for the list-to-detail hop off `GET /schedules`. To change a schedule, set it on its device via `PUT /{type}/{id}/schedule`. The route is published ahead of the scheduler; every call returns 501 unti…
- [List schedules](https://docs.amps.ai/api-reference/schedules/list-schedules.md): Return a paginated list of the schedules the API key can access, across every device, newest first. This is the lifted cross-device read of the schedules that are set on each device via `PUT /{type}/{id}/schedule`; it mirrors `GET /actions`. Filter by `deviceId`, lifecycle `state`, or end-user `user…
- [Get Solar Inverter state](https://docs.amps.ai/api-reference/solar-inverter/get-solar-inverter-state.md): Retrieve the current state of a solar inverter device including power production, status, and energy totals
- [List solar inverter devices](https://docs.amps.ai/api-reference/solar-inverter/list-solar-inverter-devices.md): Get a paginated list of solar inverter devices with their last pull state
- [Push solar inverter action (unsupported)](https://docs.amps.ai/api-reference/solar-inverter/push-solar-inverter-action-unsupported.md): Solar inverters are read-only. This route always returns `422 DIRECT_ACTION_UNSUPPORTED`; there is no imperative control surface for solar inverters.
- [Revoke user consent](https://docs.amps.ai/api-reference/users/revoke-user-consent.md): Revoke consent for a user. Stored credentials are deleted and the affected devices stop receiving pulls and pushes. Pass a `deviceIds` array to scope the revocation; omit it to revoke every device under the user.
- [Get vehicle state](https://docs.amps.ai/api-reference/vehicle/get-vehicle-state.md): Retrieve the current state of a vehicle device including battery level, range, charging status, and capacity
- [List vehicle devices](https://docs.amps.ai/api-reference/vehicle/list-vehicle-devices.md): Get a paginated list of vehicle devices with their last pull state
- [Push vehicle action (unsupported)](https://docs.amps.ai/api-reference/vehicle/push-vehicle-action-unsupported.md): Vehicles are read-only. This route always returns `422 DIRECT_ACTION_UNSUPPORTED`; there is no imperative control surface for vehicles.
- [Blog](https://docs.amps.ai/blog.md): Long-form writing on the Amps platform, the canonical model, OEM integration patterns, and the energy industry context that surrounds them.
- [How Amps works](https://docs.amps.ai/concepts/architecture.md): The three layers a single API uses to stay honest across very different devices. Brokerage, not VPP. Sync reads, async writes.
- [Auth Model](https://docs.amps.ai/concepts/auth-model.md): API key authentication. Sandbox and live environments isolated by key metadata, with full data isolation between the two.
- [Canonical Actions](https://docs.amps.ai/concepts/canonical-actions.md): One intent-based push grammar across batteries, EV chargers, and thermostats: mode-keyed commands, Quantity parameters, conflict strategies.
- [Capabilities](https://docs.amps.ai/concepts/capabilities.md): Per-device capability introspection across batteries, EV chargers, and thermostats. Presence-based contract narrowing. One commands shape, every device type.
- [Conflict Resolution](https://docs.amps.ai/concepts/conflict-resolution.md): How onConflict resolves overlap. cancel_and_replace and queue_after strategies, the 409 CONFLICT envelope, plus SCHEDULER_ACTIVE.
- [Device State](https://docs.amps.ai/concepts/device-state.md): Three-tier device state: cache, live OEM call, last-known fallback. Sync metadata, source provenance, expedited refresh.
- [Error Envelope](https://docs.amps.ai/concepts/error-envelope.md): Canonical envelope for every rejection. Code taxonomy across 400, 401, 403, 404, 409, 410, 422, 429, 500, 502, 503, and 504, plus when to retry and when to fix the body.
- [Scheduling](https://docs.amps.ai/concepts/scheduling.md): A device schedule is a list of slots set on the device. A slot is a push action plus an optional recurrence. Push is still the only execution primitive.
- [Webhook Model](https://docs.amps.ai/concepts/webhook-model.md): Event taxonomy for action lifecycle. Delayed delivery, retries with backoff, signed payloads. Sandbox vs live timing.
- [What to expect](https://docs.amps.ai/concepts/what-to-expect.md): Canonical vocabulary not behaviour. Self-documenting Quantity requests. Capability-driven design. Honest API with no hidden defaults.
- [API Authentication](https://docs.amps.ai/get-started/authentication.md): Authenticate via x-api-key header against api.amps.ai. The key prefix selects the environment: sk_test_ for sandbox, sk_live_ for live.
- [Environments](https://docs.amps.ai/get-started/environments.md): One Public API host serves two environments. Your sk_test_ key routes to sandbox simulations, your sk_live_ key to real OEM devices. The key prefix decides.
- [Platform Overview](https://docs.amps.ai/get-started/platform-overview.md): Five DER device types reachable through one REST API. Pull state, push commands, receive webhook callbacks. Sandbox and live share the contract.
- [Quickstart](https://docs.amps.ai/get-started/quickstart.md): Integrate Amps in four steps: get sandbox keys, send users through Link UI, pull device state, push the first action. Includes a worked example.
- [Get Sandbox Access](https://docs.amps.ai/get-started/sandbox-access.md): Request a sandbox API key. Build and test integrations against simulated devices across every supported OEM, with no live credentials required.
- [Switch a Battery to Auto Balanced](https://docs.amps.ai/guides/cookbook/auto-balanced.md): Hand control of a battery back to the platform with auto.balanced. Charges when solar is plentiful, discharges when the home draws power.
- [Cancel a Scheduled Action](https://docs.amps.ai/guides/cookbook/cancel-action.md): Cancel an action two ways: drop a scheduled action by actionId, or push fresh with onConflict cancel_and_replace to override an in-flight action.
- [Discharge During a Peak Window](https://docs.amps.ai/guides/cookbook/discharge-windowed.md): Force-discharge a battery during a peak-demand window with a lower SoC limit. Curl, JSON response, follow-up state poll.
- [Cap an EV Charger's Power](https://docs.amps.ai/guides/cookbook/ev-charger-set-power.md): Set an EV charger's maximum charging power as a device setting, then start and stop sessions with the charge and idle commands.
- [Handle a 409 Conflict](https://docs.amps.ai/guides/cookbook/handle-conflict.md): Resolve 409 CONFLICT when an action is in flight. Use onConflict cancel_and_replace, queue_after, or wait. Plus SCHEDULER_ACTIVE recovery.
- [Hold an HVAC Device at a Fixed Mode](https://docs.amps.ai/guides/cookbook/hvac-permanent-hold.md): Override the native schedule by pushing an operation mode (heat, cool, auto), then release it with follow_schedule. Request, lifecycle, and release.
- [Schedule a Charge for Later](https://docs.amps.ai/guides/cookbook/schedule-charge-later.md): Schedule a battery charge for later: defer it with a bare start, or bound a cheap-rate window with start and end. Capability check, curl, action lifecycle, cancellation.
- [Subscribe to Webhooks](https://docs.amps.ai/guides/cookbook/subscribe-webhooks.md): Register a webhook URL, receive push.completed and push.failed events, verify the signature, and dedupe by the svix-id header.
- [Link UI Customization](https://docs.amps.ai/guides/link-ui/customization.md): Tune the Link UI flow with query parameters: sandbox, deviceType, externalUserRef, skipDeviceSelection, and maxDevices.
- [Getting Started with Link UI](https://docs.amps.ai/guides/link-ui/getting-started.md): Six-step auth at auth.amps.ai/{appId}: device-type, OEM, credentials (username/password, API key, OAuth2), MFA, device select, and consent.
- [How to receive webhooks](https://docs.amps.ai/guides/webhooks/receive.md): Configure a webhook endpoint for push and device connection events. Flat payloads, at-least-once delivery, ~10s in live, ~3min in sandbox, HMAC-signed.
- [How to verify webhook signatures](https://docs.amps.ai/guides/webhooks/verify-signatures.md): Every Amps webhook carries a signature. Verify with the SDK or HMAC SHA-256, reject signatures older than 5 minutes, dedupe on the svix-id header.
- [Introduction](https://docs.amps.ai/index.md): Unified REST API for Distributed Energy Resources. Read state and push commands to batteries, EV chargers, HVAC, solar inverters, and vehicles.
- [Battery Cheat Sheet](https://docs.amps.ai/reference/battery-cheat-sheet.md): Quick reference for the canonical Amps battery surface: modes, parameters, action lifecycle, conflict strategies, settings, environments, errors.
- [Device error codes](https://docs.amps.ai/reference/error-codes.md): Canonical error codes the API returns when a device manufacturer rejects a push, pull, or settings request. Stable code, HTTP status, API-owned message, and what to do.
- [Glossary](https://docs.amps.ai/reference/glossary.md): Energy industry terminology for developers. kWh, demand response, VPP, DSO, time-of-use tariffs, OCPP, FCAS, balancing services, and more.
- [Types](https://docs.amps.ai/reference/webhook-types.md): Webhook event reference. push.completed, push.failed, and the device connection events fire with flat payloads; the event type rides in the svix headers.

## OpenAPI Specs

- [openapi](https://docs.amps.ai/openapi.json)