# 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 `type` field discriminates the device family and the `parameters` shape.
- [Get battery state](https://docs.amps.ai/api-reference/battery/get-battery-state.md): Retrieve the current state and capabilities of a battery device.
- [List actions for a device](https://docs.amps.ai/api-reference/battery/list-actions-for-a-device.md): Returns a paginated list of actions for a battery device, optionally filtered by lifecycle state. Useful for finding scheduled actions to cancel or completed actions to inspect.
- [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 connector picks them up; deferred actions (with `start`) fire at the requested time. The action is processed asynchronously and a webhook is sent on completion.
- [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`.
- [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
- [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.
- [Health check](https://docs.amps.ai/api-reference/health/health-check.md): Returns the current health status of the API
- [Liveness check](https://docs.amps.ai/api-reference/health/liveness-check.md): Returns whether the service is alive
- [Readiness check](https://docs.amps.ai/api-reference/health/readiness-check.md): Returns whether the service is ready to accept requests
- [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
- [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.
- [Cancel a schedule](https://docs.amps.ai/api-reference/schedules/cancel-a-schedule.md): Cancel an active schedule. Scheduled push actions that have not yet fired are cancelled; in-flight and already-completed actions are left alone. The route is published ahead of the implementation; every call returns 501 until the scheduler lands.
- [Create a schedule](https://docs.amps.ai/api-reference/schedules/create-a-schedule.md): Create a coordinated schedule of actions for a device. A schedule is a group of `slots` that materialise into push actions at fire time, with optional `recurrence` rules that top up a rolling materialisation horizon. Slot variants are mutually exclusive: `at` (absolute timestamp) or `time` (wall-clo…
- [Get a schedule](https://docs.amps.ai/api-reference/schedules/get-a-schedule.md): Retrieve a single schedule including its slots, recurrence, and current state. The route is published ahead of the implementation; every call returns 501 until the scheduler lands.
- [List schedules](https://docs.amps.ai/api-reference/schedules/list-schedules.md): Return a paginated list of schedules for a device, filtered by status. The route is published ahead of the implementation; every call returns 501 until the scheduler lands.
- [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
- [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
- [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): Canonical action shape: command modes (charge, discharge, idle, auto.balanced, auto.reserve, auto.export), Quantity parameters, conflict strategies.
- [Capabilities](https://docs.amps.ai/concepts/capabilities.md): Per-device capability introspection. Presence-based contract narrowing. Commands and settings response shape. Same surface, different physics.
- [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 401, 403, 404, 409, 422, 500, and 503, plus when to retry and when to fix the body.
- [Scheduling](https://docs.amps.ai/concepts/scheduling.md): Push is the only execution primitive. Schedules coordinate pushes via slots and recurrence. Lifecycle states and the start/end model.
- [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. Sandbox keys (sk_sandbox_) target sandbox-api.amps.ai; live keys (sk_live_) target api.amps.ai.
- [Environments](https://docs.amps.ai/get-started/environments.md): Sandbox runs UTC device simulations at sandbox-api.amps.ai with sk_sandbox_ keys. Live targets OEM devices at api.amps.ai with sk_live_ keys.
- [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.
- [Charge a Battery Overnight](https://docs.amps.ai/guides/cookbook/charge-overnight.md): Schedule a battery to charge to 90% during a cheap-rate window from 22:00 to 05:00 UTC. Curl, JSON response, lifecycle, webhook setup.
- [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 the maximum charging power on an EV charger. Throttle a session, balance against household demand, or match a tariff window.
- [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.
- [Set a Permanent Hold on an HVAC Device](https://docs.amps.ai/guides/cookbook/hvac-permanent-hold.md): Override the HVAC schedule with a permanent hold at fixed heat and cool setpoints. Walkthrough of request, lifecycle, follow_schedule release.
- [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 eventId.
- [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.completed and push.failed terminal events. 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 eventId.
- [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.
- [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 and push.failed fire with parameters and result or error envelope. Device connection events are planned.

## OpenAPI Specs

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