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

# Quickstart

> Read a sandbox battery, send it a charge command, and confirm the result.

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.

<Info>
  You need a sandbox API key. [Request sandbox access](https://tally.so/r/D4zgZE).
</Info>

## 1. Set your API key

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

```bash theme={null}
export AMPS_API_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
```

## 2. Find a battery

```bash theme={null}
curl https://api.amps.ai/battery \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "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](/guides/link-ui).

## 3. Read its state

```bash theme={null}
curl https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "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

```bash theme={null}
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" } }
    }
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.amps.ai/actions/action_qjSucnQFAk \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "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](/guides/webhooks) instead of polling.

## Next steps

<CardGroup cols={2}>
  <Card title="Push" icon="arrow-up" href="/guides/push">
    Schedule commands, handle conflicts, cancel actions.
  </Card>

  <Card title="Pull" icon="arrow-down" href="/guides/pull">
    What device state contains and how fresh it is.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Get notified when an action completes.
  </Card>

  <Card title="Battery cookbook" icon="battery-full" href="/cookbooks/battery">
    Charge in a cheap-rate window, auto-balance, and more.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.