# Automating Device Remediation

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/devices`](/api/devices)
- [`POST /v1/tasks`](/api/tasks)
- [`GET /v1/tasks/{id}`](/api/tasks)

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

The API executes remediation tasks across one or more devices and reports the outcome of each, so
remediation can be driven from the systems and workflows your teams already operate, or built into
new workflows and automations of your own.

## Scenarios

- **Scheduled credential rotation.** Rotate device passwords across the fleet on a defined schedule
  from your orchestration system.
- **Ticket-driven remediation.** Execute a task from your ITSM or ticketing tool and post the result
  back to the ticket.
- **Certificate lifecycle automation.** Rotate SSL certificates ahead of expiry as part of your
  certificate management process.
- **Response to monitoring.** Execute remediation automatically from a condition detected through
  [Monitoring](/use-cases/monitoring).

## Check task availability

Not every device supports every task. The `availableTask` object on a device reports which tasks can
be executed on it, so filter the target devices before executing:

```json
"availableTask": {
  "hardenDevice": false,
  "restartDevice": true,
  "rotate8021xCertificate": false,
  "rotatePassword": true,
  "rotateSslCertificate": true,
  "upgradeFirmware": true
}
```

## Execute a task

A single request executes a task across any number of devices, and returns the `taskId` used to
track it:

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

```json
{ "taskId": "23bpozz1mpjjedtr" }
```

Tasks run asynchronously. The execution and polling pattern, the available task types, and the
per-task-type payloads are described in [Asynchronous Tasks](/guides/async-tasks).

## Verify the outcome

Poll `GET /v1/tasks/{id}` until every device task has a `status` of `completed`, then read the
`result` of each device task. Device tasks that did not succeed can be retried independently of the
rest.

```bash
curl "https://api.securithings.com/v1/tasks/23bpozz1mpjjedtr" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"
```