Search devices for multiple apps

POST /api/v1/org/{orgId}/perch/status

Search Devices

Searches for devices matching the provided application IDs within the specified organization.

This endpoint accepts a SearchDevicesRequest with a queryAppIds filter to retrieve the status of cloud-based security scan infrastructure for multiple applications in a single request. All requested application IDs must belong to the specified organization.

Request

Provide a SearchDevicesRequest body with a queryAppIds filter in the page.filters field. If no queryAppIds filter is provided, the endpoint returns an empty response.

Response

Parameter	Default	Description
perchDevices	[]
totalCount	0
pageInfo	{}

Errors

403 Forbidden: One or more application IDs do not belong to the specified organization.
404 Not Found: Organization not found or user doesn't have access.

Requires read:device permission.

Path parameters

orgIdstring · uuidrequired

UUID identifier for this StackHawk Organization.

Body

orgId

string

page

pagination.Page

Hide child attributesShow child attributes

page.filters

pagination.Filter[]

Generic filters that each type can define for its needs (isConnected=true, hasMapping=false, etc)

Hide child attributesShow child attributes

page.filters.multi

pagination.MultiValue

Hide child attributesShow child attributes

page.filters.multi.values

string[]

The values of a given filter to filter on.

page.filters.name

string

The name of the filter to apply.

page.filters.value

string

A single value to filter on.

page.number

integer<int32>

The page number to retrieve - 0 based

page.query

string

The query string to filter the results.

page.size

integer<int32>

the page size to retrieve.

page.sortOptions

pagination.SortOptions

Hide child attributesShow child attributes

page.sortOptions.direction

enum<string>

The direction to sort the results.

3 available options

ASCDESCUNSORTED

page.sortOptions.field

string

Generic here, each type should define its own Enums + Converters

Response

pageInfo

pagination.PageInfo

Hide child attributesShow child attributes

pageInfo.hasNext

boolean

Whether or not there is a next page.

pageInfo.hasPrev

boolean

Whether or not there is a previous page.

pageInfo.nextPage

pagination.Page

Hide child attributesShow child attributes

pageInfo.nextPage.filters

pagination.Filter[]

Generic filters that each type can define for its needs (isConnected=true, hasMapping=false, etc)

Hide child attributesShow child attributes

pageInfo.nextPage.filters.multi

pagination.MultiValue

Hide child attributesShow child attributes

pageInfo.nextPage.filters.multi.values

string[]

The values of a given filter to filter on.

pageInfo.nextPage.filters.name

string

The name of the filter to apply.

pageInfo.nextPage.filters.value

string

A single value to filter on.

pageInfo.nextPage.number

integer<int32>

The page number to retrieve - 0 based

pageInfo.nextPage.query

string

The query string to filter the results.

pageInfo.nextPage.size

integer<int32>

the page size to retrieve.

pageInfo.nextPage.sortOptions

pagination.SortOptions

Hide child attributesShow child attributes

pageInfo.nextPage.sortOptions.direction

enum<string>

The direction to sort the results.

3 available options

ASCDESCUNSORTED

pageInfo.nextPage.sortOptions.field

string

Generic here, each type should define its own Enums + Converters

pageInfo.prevPage

pagination.Page

Hide child attributesShow child attributes

pageInfo.prevPage.filters

pagination.Filter[]

Generic filters that each type can define for its needs (isConnected=true, hasMapping=false, etc)

Hide child attributesShow child attributes

pageInfo.prevPage.filters.multi

pagination.MultiValue

Hide child attributesShow child attributes

pageInfo.prevPage.filters.multi.values

string[]

The values of a given filter to filter on.

pageInfo.prevPage.filters.name

string

The name of the filter to apply.

pageInfo.prevPage.filters.value

string

A single value to filter on.

pageInfo.prevPage.number

integer<int32>

The page number to retrieve - 0 based

pageInfo.prevPage.query

string

The query string to filter the results.

pageInfo.prevPage.size

integer<int32>

the page size to retrieve.

pageInfo.prevPage.sortOptions

pagination.SortOptions

Hide child attributesShow child attributes

pageInfo.prevPage.sortOptions.direction

enum<string>

The direction to sort the results.

3 available options

ASCDESCUNSORTED

pageInfo.prevPage.sortOptions.field

string

Generic here, each type should define its own Enums + Converters

pageInfo.totalCount

integer<int64>

The total number of results.

perchDevices

perch.PerchDevice[]

Hide child attributesShow child attributes

perchDevices.applicationId

string

perchDevices.command

perch.PerchCommand

Hide child attributesShow child attributes

perchDevices.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

perchDevices.command.config

string

perchDevices.command.errors

perch.PerchError[]

Hide child attributesShow child attributes

perchDevices.command.errors.errorType

enum<string>

4 available options

UNKNOWNAUTHENTICATIONPROVISIONINGDEVICE

perchDevices.command.errors.message

string

perchDevices.command.id

string

perchDevices.command.name

string

perchDevices.configValidationResult

perch.ConfigValidationResult

Hide child attributesShow child attributes

perchDevices.configValidationResult.errors

string[]

perchDevices.configValidationResult.fieldErrors

perch.ValidationFieldError[]

Hide child attributesShow child attributes

perchDevices.configValidationResult.fieldErrors.fieldName

string

perchDevices.configValidationResult.fieldErrors.jsonPath

string

perchDevices.configValidationResult.fieldErrors.message

string

perchDevices.configValidationResult.message

string

perchDevices.configValidationResult.success

boolean

perchDevices.createdDate

integer<int64>

perchDevices.deviceAddress

string

perchDevices.id

string

perchDevices.name

string

perchDevices.orgId

string

perchDevices.podType

enum<string>

5 available options

HAWKSCANSCREENRPROFILECONFIG_VALIDATIONSCAN

perchDevices.scanId

string

perchDevices.status

string

perchDevices.updatedDate

integer<int64>

perchDevices.userId

string

totalCount

integer<int64>

pageInfo

pagination.PageInfo

Hide child attributesShow child attributes

pageInfo.hasNext

boolean

Whether or not there is a next page.

pageInfo.hasPrev

boolean

Whether or not there is a previous page.

pageInfo.nextPage

pagination.Page

Hide child attributesShow child attributes

pageInfo.nextPage.filters

pagination.Filter[]

Generic filters that each type can define for its needs (isConnected=true, hasMapping=false, etc)

Hide child attributesShow child attributes

pageInfo.nextPage.filters.multi

pagination.MultiValue

Hide child attributesShow child attributes

pageInfo.nextPage.filters.multi.values

string[]

The values of a given filter to filter on.

pageInfo.nextPage.filters.name

string

The name of the filter to apply.

pageInfo.nextPage.filters.value

string

A single value to filter on.

pageInfo.nextPage.number

integer<int32>

The page number to retrieve - 0 based

pageInfo.nextPage.query

string

The query string to filter the results.

pageInfo.nextPage.size

integer<int32>

the page size to retrieve.

pageInfo.nextPage.sortOptions

pagination.SortOptions

Hide child attributesShow child attributes

pageInfo.nextPage.sortOptions.direction

enum<string>

The direction to sort the results.

3 available options

ASCDESCUNSORTED

pageInfo.nextPage.sortOptions.field

string

Generic here, each type should define its own Enums + Converters

pageInfo.prevPage

pagination.Page

Hide child attributesShow child attributes

pageInfo.prevPage.filters

pagination.Filter[]

Generic filters that each type can define for its needs (isConnected=true, hasMapping=false, etc)

Hide child attributesShow child attributes

pageInfo.prevPage.filters.multi

pagination.MultiValue

Hide child attributesShow child attributes

pageInfo.prevPage.filters.multi.values

string[]

The values of a given filter to filter on.

pageInfo.prevPage.filters.name

string

The name of the filter to apply.

pageInfo.prevPage.filters.value

string

A single value to filter on.

pageInfo.prevPage.number

integer<int32>

The page number to retrieve - 0 based

pageInfo.prevPage.query

string

The query string to filter the results.

pageInfo.prevPage.size

integer<int32>

the page size to retrieve.

pageInfo.prevPage.sortOptions

pagination.SortOptions

Hide child attributesShow child attributes

pageInfo.prevPage.sortOptions.direction

enum<string>

The direction to sort the results.

3 available options

ASCDESCUNSORTED

pageInfo.prevPage.sortOptions.field

string

Generic here, each type should define its own Enums + Converters

pageInfo.totalCount

integer<int64>

The total number of results.

perchDevices

perch.PerchDevice[]

Hide child attributesShow child attributes

perchDevices.applicationId

string

perchDevices.command

perch.PerchCommand

Hide child attributesShow child attributes

perchDevices.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

perchDevices.command.config

string

perchDevices.command.errors

perch.PerchError[]

Hide child attributesShow child attributes

perchDevices.command.errors.errorType

enum<string>

4 available options

UNKNOWNAUTHENTICATIONPROVISIONINGDEVICE

perchDevices.command.errors.message

string

perchDevices.command.id

string

perchDevices.command.name

string

perchDevices.configValidationResult

perch.ConfigValidationResult

Hide child attributesShow child attributes

perchDevices.configValidationResult.errors

string[]

perchDevices.configValidationResult.fieldErrors

perch.ValidationFieldError[]

Hide child attributesShow child attributes

perchDevices.configValidationResult.fieldErrors.fieldName

string

perchDevices.configValidationResult.fieldErrors.jsonPath

string

perchDevices.configValidationResult.fieldErrors.message

string

perchDevices.configValidationResult.message

string

perchDevices.configValidationResult.success

boolean

perchDevices.createdDate

integer<int64>

perchDevices.deviceAddress

string

perchDevices.id

string

perchDevices.name

string

perchDevices.orgId

string

perchDevices.podType

enum<string>

5 available options

HAWKSCANSCREENRPROFILECONFIG_VALIDATIONSCAN

perchDevices.scanId

string

perchDevices.status

string

perchDevices.updatedDate

integer<int64>

perchDevices.userId

string

totalCount

integer<int64>

Bad Request

Unauthorized

POST /api/v1/org/{orgId}/perch/status

cURL

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

Copy

Search Devices

Request

Response

Errors

Path parameters

Body

Response

Your privacy settings