Start a hosted scan

POST /api/v1/app/{appId}/perch/start

Start a Scan

Provisions the resources needed to run a hosted security scan and starts the scan asynchronously.

Prerequisites

The application must be a Hosted application type
The target domain must be verified for hosted scanning
No scan should already be running for this application

Request Body

Parameter	Default	Description
id	""
name	""
command	{}

Response

Parameter	Default	Description
scanKey	""

{
	"scanKey": ""
}

Errors

409 Conflict: A scan is already running for this application
400 Bad Request: The application is not verified for cloud scanning or is not a cloud application
404 Not Found: Application not found or user doesn't have access

👥 Teams Supported If the application belongs to a StackHawk Team, only members of the Team can call this endpoint. 🧾 Audited This is recorded as SCAN_STARTED User Activity.

Requires write:scan permission.

Path parameters

appIdstring · uuidrequired

UUID identifier for this StackHawk Application.

Query parameters

envIdstring · uuid

Optional UUID identifier of the environment to scan. Defaults to the app's default environment.

Body

command

perch.PerchCommand

Hide child attributesShow child attributes

command.command

enum<string>

12 available options

NOOPSCAN_STARTSCAN_STOPRESCAN_STARTSCREENR_START_BROWSERSCREENR_START_MCPSCREENR_START_SCREENRSCREENR_START_AUTH_ANALYSISSCREENR_EXPORT_SESSIONSCREENR_STOPCONFIG_VALIDATEAUTH_VALIDATE

command.config

string

command.errors

perch.PerchError[]

Hide child attributesShow child attributes

command.errors.errorType

enum<string>

4 available options

UNKNOWNAUTHENTICATIONPROVISIONINGDEVICE

command.errors.message

string

command.id

string

command.name

string

name

string

Response

scanKey

string

scanKey

string

Bad Request

Unauthorized

POST /api/v1/app/{appId}/perch/start

cURL

curl --request POST \
  --url 'https://api.stackhawk.com/api/v1/app/{appId}/perch/start' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Copy

Start a hosted scan

Start a Scan

Prerequisites

Request Body

Response

Errors

Path parameters

Query parameters

Body

Response

Your privacy settings