Launch a pentest
Queues a hosted pentest. It runs asynchronously: poll Get a pentest with the returned scanId, or subscribe to the pentest.completed webhook. An identical active launch may be reused, in which case the response names that pentest.
Scope. With endpointIds, exactly those discovered endpoints are tested. Find them with List applications and List endpoints, and send endpoint id values, not URLs or application IDs. Without endpointIds, every eligible application in the workspace is tested. Applications must have a linked domain with pentesting enabled, verification where required, and discovered endpoints; a selected application that is not ready is rejected rather than silently dropped.
Depth. scanLevel defaults to priority, or to full with endpointIds, which accepts only full.
Branch. branch must match the connected repository’s configured target branch; omitting it uses that branch. It cannot be combined with endpointIds. To test the changes between two commits, use CI dispatch instead.
Unknown fields and invalid scope return 400 before a pentest is created; the scope is never widened after a validation failure.
Requires the pentests:launch API key scope.
Authentication
A workspace API key, sent as Authorization: Bearer.
A workspace API key, sent as x-api-key.
Request
Configured repository branch only; cannot be combined with endpointIds.
Legacy launches default to priority; exact endpoint launches require full and default to full.
Exact nonempty list of discovered endpoint UUIDs in this workspace (maximum 1000).
Active knowledge base entry UUIDs to attach as context for this run (maximum 20).
Response
Pentest ID. Pass it to GET /pentests/{pentestId}.