Skip to main content

​
Prerequisites

Before you begin, you’ll need:
  • An Amps AI customer account
  • API keys (sandbox and/or live)
  • A webhook endpoint URL (optional but recommended)
  • Access to the Link UI for device authentication

​
Step 1: Get Your API Keys

You will need to request Sandbox access before completing these steps. Get sandbox access to continue.
1

Create Account

Sign up for an Amps AI account in the dashboard
2

Generate API Keys

Create separate API keys for sandbox and live environments in your dashboard settings
3

Configure Webhooks

Set up webhook endpoints to receive device events and action notifications
Keep your API keys secure. Never commit them to version control or expose them in client-side code.
Direct your end users to the Link UI to authenticate with OEMs and connect their devices: Base URL: 
https://auth.amps.ai/{appId}
For Sandbox Testing: 
https://auth.amps.ai/{appId}?sandbox=true
For Production: 
https://auth.amps.ai/{appId}
Replace {appId} with your actual application ID from the dashboard. The Link UI handles the entire authentication flow including OEM selection, credential entry, MFA (if required), device selection, and consent collection.

Environments Guide

Learn more about Sandbox and Live environments

​
Step 3: Make Your First API Call

Test your integration by retrieving device data:
curl
curl -X GET "https://api.amps.ai/battery/{deviceId}" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

​
Example Response

{
  "id": "device_abc123",
  "vendor": "tesla",
  "state": {
    "level": 85,
    "status": "charging",
    "capacity": 13.5,
    "chargeRate": 5.2
  },
  "metadata": {
    "model": "Powerwall 2",
    "source": "cache"
  }
}

​
Step 4: Set Up Webhooks

Configure webhook endpoints to receive real-time notifications:
  1. Add your webhook URL in the dashboard
  2. Subscribe to the events you want to receive:
    • device.connected
    • device.disconnected
    • push.completed
    • push.failed
  3. Verify webhook signatures to ensure requests are from Amps AI

Webhook Setup Guide

Learn more about configuring webhooks

​
Step 5: Push Your First Command

Send a command to a device (example: set HVAC temperature):
curl
curl -X POST "https://api.amps.ai/hvac/{deviceId}" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_permanent_hold",
    "mode": "auto",
    "heatSetpoint": 68,
    "coolSetpoint": 76
  }'
The API returns an action ID immediately. Use webhooks or polling to check the action status.

​
Next Steps

Authentication

Learn about API authentication

Link UI Guide

Understand the device connection flow

Webhooks

Set up webhook endpoints

API Reference

Explore the full API documentation

​
Common Tasks

Use the sandbox environment! It provides realistic device simulations based on UTC time patterns, allowing you to test your integration without connecting real devices. See the Environments Guide for details on sandbox behavior.
Each device has a unique deviceId. You can list all devices for a user using the list endpoints (e.g., GET /battery) and filter by userId.
The API will return cached data if available, or you’ll receive a 404 error. Webhooks will notify you of connection status changes.
Actions are processed asynchronously. Use the action ID returned from push endpoints to:
  • Poll the action status endpoint (e.g., GET /hvac/actions/{actionId})
  • Receive webhook notifications when actions complete