---
title: "Create an ad-hoc scan"
method: POST
path: "/v1/scan"
tags: ["Scan"]
---

# Create an ad-hoc scan

`POST /v1/scan`

## Request

- Base URL: `https://help.puppet.com/api/public`
- URL: `https://help.puppet.com/api/public/v1/scan`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/puppet/apis/puppet-comply-api/docs/v1/scan/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates scan request and runs scan on nodes that match filter criteria if specified.

To use this endpoint, you must have one of the following roles:
`comply-admin`
`comply-operator`

## Request body

- object
  - `filters` ScanFilters
    - `environments` string[], nullable: If specified, only nodes in at least one of the given environments will be included.
    - `hostnames` string[], nullable: If specified, nodes with at least one of the hostname will be included.
    - `node_groups` string[], nullable: If specified, only nodes in at least one of the given node groups will be included.
    - `operating_systems` string[], nullable: If specified, only nodes of the given operating systems will be included. Each operating system must be specified as a string with the name and version separated by a space.
  - `scan-type` 'desired', required: The type of scan to be tiggrered.

## Response `201`

CreateDesiredScanResponse represents the response to a scan request.

- object
  - `created_at` string, date-time, required: The time at which the scan was created.
  - `errored` integer, required: The number of nodes that errored in scan.
  - `failed` integer, required: The number of nodes that failed in scan.
  - `finished` integer, required: The number of nodes that finished in scan.
  - `finished_at` string, date-time, nullable: The time at which the scan finished.
  - `id` string, required: The ID of the scan.
  - `name` string, required: The name of the scan.
  - `nodes_scanned` integer, required: The number of nodes scanned.
  - `status` 'started' | 'finished' | 'failed', required: The status of the inventory sync job.
  - `type` string, required: The type of scan.

## Other responses

- `422`: NoNodesToScanResponse is returned when input to scan request did not match any nodes
- `default`: ErrorResponse is the default error response.

---

[API](https://skmtc.dev/puppet/apis/puppet-comply-api.md) - [All operations](https://skmtc.dev/puppet/apis/puppet-comply-api/llms.txt) - [OpenAPI document](https://skmtc.dev/puppet/apis/puppet-comply-api/revisions/0a7ac90117d7?raw)