Quickstart

Read a battery’s state, tell it to charge, and check that the command completed. You’ll use a sandbox battery, so nothing real is controlled.

You need a sandbox API key. Request sandbox access.

1. Set your API key

Sandbox keys start with sk_test_. Send yours in the x-api-key header on every request.

export AMPS_API_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

2. Find a battery

curl https://api.amps.ai/battery \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "items": [{ "id": "device_abc123", "vendor": "example_vendor_a" }],
    "pagination": { "limit": 10, "offset": 0, "total": 1, "hasMore": false }
  }
}

Copy the id. If the list is empty, connect a sandbox battery through Link UI.

3. Read its state

curl https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "state": {
      "status": "idle",
      "level": 67,
      "capacity": 10.4,
      "currentMode": "auto.balance"
    },
    "commands": {
      "charge": {
        "parameters": {
          "target": { "unit": "percent", "min": 0, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      }
    }
  }
}

state is what the battery is doing now. commands lists what it accepts: here, charge takes a target between 0 and 100 percent.

4. Send a charge command

curl -X POST https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "command": "charge",
      "parameters": { "target": { "value": 80, "unit": "percent" } }
    }
  }'

{
  "success": true,
  "data": {
    "id": "action_qjSucnQFAk",
    "command": "charge",
    "state": "acknowledged",
    "links": { "self": "/actions/action_qjSucnQFAk" }
  }
}

The API returns 202 Accepted. Commands run asynchronously, so this means Amps has accepted the command, not that the battery has started charging.

5. Check the result

curl https://api.amps.ai/actions/action_qjSucnQFAk \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "action_qjSucnQFAk",
    "state": "completed",
    "result": { "success": true }
  }
}

state moves from acknowledged to completed or failed. Read the battery again and it reports status: "charging". In production, subscribe to webhooks instead of polling.

Next steps

Push

Schedule commands, handle conflicts, cancel actions.

Pull

What device state contains and how fresh it is.

Webhooks

Get notified when an action completes.

Battery cookbook

Charge in a cheap-rate window, auto-balance, and more.

Get started

API Reference

Guides

Cookbooks

1. Set your API key

2. Find a battery

3. Read its state

4. Send a charge command

5. Check the result

Next steps

Push

Pull

Webhooks

Battery cookbook

​1. Set your API key

​2. Find a battery

​3. Read its state

​4. Send a charge command

​5. Check the result

​Next steps

Push

Pull

Webhooks

Battery cookbook

1. Set your API key

2. Find a battery

3. Read its state

4. Send a charge command

5. Check the result

Next steps