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

# Create an ad-hoc custom scan

`POST /v1/custom-scan`

## Request

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

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

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

## Request body

- object
  - `benchmark_id` integer, required: The benchmark for associated profile.
  - `custom_profile_id` integer, nullable: The custom profile ID to be used for the scan.
  - `profile_id` integer, nullable: The profile ID to be used for the scan.
  - `scan_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` 'custom', required: ScanType is the type of scan to run.

## Response `201`

CreateCustomScanResponse 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)