# Device

A device is the basic unit that most of Firewalla's feature set, including monitoring, alarms, and traffic filtering, is built with. Each device represents either a physical device, a network interface, or a VPN client.

## Get Devices

[!badge variant="primary" text="GET"] <span style="color:grey">https://msp_domain</span>**/v2/devices**

<p class="parameters">Parameters</p>
<p class="header">Header</p>

| Name                                          | Value                 |
| --------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |

<p class="header">Query String</p>

| Name  | Value                              |
| ----  | ---------------------------------- |
| box   | Gets devices under a specific Firewalla box, must be supplied with the ID of a box
| group | Gets devices under a specific Firewalla box group, must be supplied with the ID of a box group

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>

</p>

A JSON array of [Devices](../data-models/device.md/#device)

```json
[
  {
    "id": "AA:BB:CC:DD:EE:FF",
    "macVendor": "Apple Inc.",
    "gid": "00000000-0000-0000-0000-000000000000",
    "ip": "192.168.120.1",
    "ipReserved": true,
    "name": "My Iphone",
    "online": true,
    "lastSeen": "1647832113.571",
    "network": {
      "name": "Home Office",
      "id": "00000000-1111-1111-1111-000000000000"
    },
    "group": {
      "name": "Kid",
      "id": "15"
    },
    "totalDownload": 45185926,
    "totalUpload": 55977001
  }
]

```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
const axios = require('axios');

// Change these three configurations to what you need
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "YOUR_PERSONAL_ACCESS_TOKEN";

axios({
    method: 'get',
    url: `https://${msp_domain}/v2/devices`,
    headers: {
        Authorization: `Token ${token}`
    }
}).then((res) => {
    let data = res.data;
    console.log(data);
})
```
+++ cURL
```bash
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]'

# Get a list of device names
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' | jq '.[].name'

# Get all devices with a reserved IP
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq '.[] | select(.ipReserved == true) | "\(.name), \(.ip), \(.id), Reserved:\(.ipReserved)"'

# Get a list of group names
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq 'unique_by(.group.name) | .[] | .group.name | select (. != null)'

# Get a list of devices belong to a group
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq '.[] | select (.group.name == "testGroup1")'
```
+++

## Update Device

[!badge variant="primary" text="PATCH"] <span style="color:grey">https://msp_domain</span>**/v2/boxes/:gid/devices/:id**

> [!note] Note
> Currently, only the `name` field can be modified. Any other field in the request body is ignored.

<p class="parameters">Parameters</p>
<p class="header">Header</p>

| Name                                          | Value                 |
| --------------------------------------------- | --------------------- |
| Authorization <span style="color:orange">*required*</span> | Personal access token |
| Content-Type | application/json |

<p class="header">Path</p>

| Name | Value |
| ---- | ----- |
| gid <span style="color:orange">*required*</span> | The ID of the Firewalla box |
| id <span style="color:orange">*required*</span> | The ID of the device to update |

<p class="header">Request Body</p>

| Name | Type | Description |
| ---- | ---- | ----------- |
| name | String | The new name for the device (max 32 characters) |

<p class="response">Response</p>

<p class="statusCode"><svg class="green" viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>200 Success</span>

</p>

Returns the updated [Device](../data-models/device.md/#device) object.

```json
{
  "id": "AA:BB:CC:DD:EE:FF",
  "macVendor": "Apple Inc.",
  "gid": "00000000-0000-0000-0000-000000000000",
  "ip": "192.168.120.1",
  "ipReserved": true,
  "name": "Updated Device Name",
  "online": true,
  "lastSeen": "1647832113.571",
  "network": {
    "name": "Home Office",
    "id": "00000000-1111-1111-1111-000000000000"
  },
  "group": {
    "name": "Kid",
    "id": "15"
  },
  "totalDownload": 45185926,
  "totalUpload": 55977001
}
```

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>400 Bad Request</span>
</p>

Returns when the name is empty or exceeds 32 characters.

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="red"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>404 Not Found</span>
</p>

Returns when the device is not found.

<p class="statusCode">
<svg viewBox="0 0 8 16" preserveAspectRatio="xMidYMid meet" class="brown"><path d="M0 8c0-2.2 1.8-4 4-4s4 1.8 4 4-1.8 4-4 4-4-1.8-4-4z" fill="currentColor" fill-rule="evenodd"></path></svg>
<span>401 Permission Denied</span>
</p>

<p class="examples">Examples</p>

+++ Node.js
```js
const axios = require('axios');

// Change these three configurations to what you need
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "YOUR_PERSONAL_ACCESS_TOKEN";
const boxId = "00000000-0000-0000-0000-000000000000";
const deviceId = "AA:BB:CC:DD:EE:FF";

axios({
    method: 'patch',
    url: `https://${msp_domain}/v2/boxes/${boxId}/devices/${deviceId}`,
    headers: {
        Authorization: `Token ${token}`,
        'Content-Type': 'application/json'
    },
    data: {
        name: "My Updated Device"
    }
}).then((res) => {
    let data = res.data;
    console.log(data);
}).catch((error) => {
    console.error('Error:', error.response?.data || error.message);
})
```
+++ cURL
```bash
curl --request PATCH \
--url 'https://[msp_domain]/v2/boxes/[box_id]/devices/[device_id]' \
--header 'Authorization: Token [your_personal_access_token]' \
--header 'Content-Type: application/json' \
--data '{"name": "My Updated Device"}'

# Update device name with validation
curl --request PATCH \
--url 'https://[msp_domain]/v2/boxes/[box_id]/devices/[device_id]' \
--header 'Authorization: Token [your_personal_access_token]' \
--header 'Content-Type: application/json' \
--data '{"name": "New Device Name"}' | jq '.name'
```
+++