---
title: "Start a hosted scan"
method: POST
path: "/api/v1/app/{appId}/perch/start"
tags: ["Perch"]
---

# 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|""||

```json
{
	"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](https://docs.stackhawk.com/web-app/teams.html), only members of the Team can call this endpoint.
> 🧾 Audited
> This is recorded as `SCAN_STARTED` [User Activity](https://apidocs.stackhawk.com/reference/listauditactivity#user-activity-types).


> Requires `write:scan` permission.

## Path parameters

- `appId` string, uuid, required

## Query parameters

- `envId` string, uuid

## Request body

- PerchPerchCommandRequest
  - `command` PerchPerchCommand
    - `command` 'NOOP' | 'SCAN_START' | 'SCAN_STOP' | 'RESCAN_START' | 'SCREENR_START_BROWSER' | 'SCREENR_START_MCP' | 'SCREENR_START_SCREENR' | 'SCREENR_START_AUTH_ANALYSIS' | 'SCREENR_EXPORT_SESSION' | 'SCREENR_STOP' | 'CONFIG_VALIDATE' | 'AUTH_VALIDATE'
    - `config` string
    - `errors` PerchPerchError[]
      - `errorType` 'UNKNOWN' | 'AUTHENTICATION' | 'PROVISIONING' | 'DEVICE'
      - `message` string
    - `id` string
    - `name` string
  - `id` string
  - `name` string

## Response `200`

OK

- UserProvisionPerchResponse
  - `scanKey` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/stackhawk/apis/stackhawk-public-api.md) · [All operations](https://skmtc.net/stackhawk/apis/stackhawk-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stackhawk/stackhawk-public-api/versions/ad3dfd54cb63/schema)