Trigger an ad-hoc scan
trigger_scanTrigger an ad-hoc scan (permission: edit)
Run a scan against a custom url (Web/TV) or apk (Android, via /uploads), optionally replaying a saved journeyId. android_* requires apk; web_* and tv_* require url (mutually exclusive) — a 400 is returned when the target type and scanType disagree. A field that cannot take effect for the scan is a 400 with code field_not_applicable on its path: viewport and bannerOverride apply to web scans without a journeyId only, country to every scan except a web or TV journey replay (a journeyId replays at the journey's recorded location and viewport), tvPlatform to tv_* scans, maxDepth to android_compliance scans; journeyId on android_compliance is refused (only android_journey replays a journey). url is an absolute http(s) URL. The scan runs on an ephemeral target; save a test with POST /targets. country decides the proxy location, browser language and timezone; without it the scan runs from DE (locale and timezone are not accepted). Set dryRun=true to produce diffs + score for a CI gate WITHOUT mutating any journey baseline. The scan may start later if the queue is temporarily unavailable; poll its status. idempotencyKey (sent as the Idempotency-Key header): retrying the same call with the same value replays the original answer; the same value with different arguments is 422 idempotency_conflict, and 409 idempotent_in_progress means wait error.meta.retryAfter seconds and retry.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"scanType": "<scanType>"
},
"name": "trigger_scan"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| apk | No | The uploaded app: `{ gcsPath }` as POST /uploads answered it (android_* scans). | |
| url | No | Absolute http(s) URL to scan (web_* and tv_* scans). | |
| dryRun | No | true: produce diffs and score for a CI gate without changing any journey baseline; default false. | |
| country | No | Scan country (proxy location, browser language, timezone): CZ, DE, AT, IT, ES, NL, DK, FR, BE, PL, IE, SK; default DE | |
| maxDepth | No | How deep the app crawl goes (1-5); android_compliance scans only. | |
| scanType | Yes | The scan to run: android_* takes `apk`, web_* and tv_* take `url`. | |
| viewport | No | Browser viewport; web scans without a journeyId only. | |
| journeyId | No | A saved journey to replay (GET /journeys); required for android_journey, refused for android_compliance. | |
| projectId | No | Required with an organization key; must be the key's project with a project key. Missing (organization key) or not a UUID: 400 invalid_request on path projectId; a project outside the key's reach: 404. | |
| tvPlatform | No | The TV platform to emulate; tv_* scans only. | |
| bannerOverride | No | A consent-banner override object for the scan; web scans without a journeyId only. | |
| idempotencyKey | No | Optional Idempotency-Key: reuse the same value when retrying this exact call so it is applied once. |