# Manage Device Inventory

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "zudoku/ui/Accordion";

<Accordion type="single" collapsible className="not-prose mb-6 rounded-md border px-3 text-sm">
<AccordionItem value="endpoints" className="border-none">
<AccordionTrigger className="py-2 text-sm hover:no-underline">API endpoints used in this page</AccordionTrigger>
<AccordionContent className="pb-3 [&_ul]:my-0 [&_ul]:list-disc [&_ul]:ps-5 [&_ul]:space-y-1.5 [&_li]:leading-6">

- [`GET /v1/discoveredDevices`](/api/discovered-devices)
- [`POST /v1/tasks`](/api/tasks)
- [`GET /v1/tasks/{id}`](/api/tasks)
- [`GET /v1/devices`](/api/devices)

</AccordionContent>
</AccordionItem>
</Accordion>

The discovered devices inventory is populated from the device sources connected to SecuriThings, and
it is updated continuously as additional devices are discovered. A discovered device must be
onboarded before it can be managed through the SecuriThings platform.

This guide covers retrieving discovered devices and onboarding them into your managed inventory.

## Managed vs discovered

- **Managed devices** (`GET /v1/devices`) are managed through the SecuriThings platform.
- **Discovered devices** (`GET /v1/discoveredDevices`) come from the connected device sources and
  are not managed until they are onboarded.

## Scenarios

- **Discovery monitoring.** Track newly reported devices and their onboarding status over time.
- **Bulk onboarding.** Onboard every device that is ready to onboard in a single task.
- **Onboarding backlog reporting.** Report devices that require enrichment before they can be
  onboarded.

## List devices ready to onboard

Filter discovered devices by `onboardingStatus` to retrieve only the devices that can be onboarded.
Omit the filter to retrieve all discovered devices, or filter by `deviceSources.id`, `deviceType`,
`vendor`, `discoveredAfter`, or `discoveredBefore`.

```bash
curl "https://api.securithings.com/v1/discoveredDevices?onboardingStatus=readyToOnboard&limit=100" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"
```

## Onboard devices

Onboarding is an [asynchronous task](/guides/async-tasks). Collect the IDs of devices whose
`onboardingStatus` is `readyToOnboard`, then execute an `onboardDevice` task:

```bash
curl -X POST "https://api.securithings.com/v1/tasks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{
       "taskType": "onboardDevice",
       "devices": [
         { "deviceId": "9ff559ee-38b6-11f1-81cb-465864a35d0a" },
         { "deviceId": "dc7d4ef1-6bf9-11f1-b083-d27bafcacdf8" }
       ]
     }'
```

## Verify the task succeeded

The outcome of the onboarding request is reported by the task. Poll `GET /v1/tasks/{id}` until every
device task has a `status` of `completed`, then read the `result` of each device task. A `result` of
`succeeded` means the device was onboarded. See [Asynchronous Tasks](/guides/async-tasks).

## Retrieve an onboarded device

An onboarded device is part of your device inventory, and can be retrieved from the devices endpoint
by its ID:

```bash
curl "https://api.securithings.com/v1/devices/9ff559ee-38b6-11f1-81cb-465864a35d0a" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"
```