--- sourceDocument: Brazil Impact sourceDocumentLink: https://www.servicenow.com/docs/r/impact Release : - brazil ft:locale : - en-US ft:publication_title : - Brazil Impact ft:clusterId : - ipact bundleId : - ipact --- # Scan Engine Headless REST API # Scan Engine Headless REST API {#ariaid-title1} Release version: Brazil Updated September 23, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete. ## Summary of Scan Engine Headless REST API The Scan Engine Headless REST API enables ServiceNow customers to programmatically trigger security and health scans, retrieve scan findings in real-time, and integrate scan automation into business processes without using the user interface. It is designed for automated environments such as CI/CD pipelines, scheduled jobs, and custom workflows, facilitating continuous scanning and monitoring of instances, update sets, applications, or content. Show full answer Show less ## Key Features * **Automated Scan Triggering:** Start scans via REST API calls from CI/CD pipelines or scheduled workflows. * **Real-time Monitoring:** Poll scan status endpoints to monitor progress and receive immediate feedback. * **Findings Retrieval:** Programmatically access detailed scan results, including severity and affected records, for integration and reporting. * **Scan Cancellation:** Optionally cancel scans that are no longer needed before completion. * **Historical Tracking:** Retrieve findings that have been resolved over time to track improvements. * **Multiple Scan Modes:** Supports scanning at different scopes---instance, update set, application, or content. * **Health Scoring:** Provides an overall health score (0-100) to quantify scan results, useful for automated decision-making. ## How the API Works The API follows a request-response workflow: * **Trigger a Scan:** Send a POST request to start a scan and receive a unique scan result ID. * **Check Status:** Poll the status endpoint using the scan result ID to monitor scan progress and get summary metrics. * **Retrieve Findings:** After completion, fetch detailed findings to understand issues and prioritize fixes. * **Act on Results:** Use findings to automate actions such as blocking deployments, sending alerts, or generating reports. * **Optional Actions:** Cancel scans if unnecessary or query for resolved findings over time. ## Practical Use Cases * Integrate scans into CI/CD pipelines to block deployments based on security or compliance findings. * Run automated nightly health checks on CMDB or service mapping data without manual intervention. * Scan multiple applications in parallel within broader automation workflows. * Collect and analyze scan results over time to support ongoing monitoring and improvement efforts. ## Prerequisites * A ServiceNow instance with Scan Engine enabled, running Impact Platform version 12.0.0 or later. * A user account assigned the `snse.scanengineuser` role. * Valid session token or OAuth credentials for API authentication. * API access enabled on the ServiceNow instance. The Scan Engine API gives you a way to trigger scans programmatically, retrieve findings in real-time, and integrate scan automation into your business processes. Rather than running scans from the user interface, call REST endpoints from Continuous Integration/Continuous Deployment (CI/CD) pipelines, scheduled jobs, or custom workflows. With Scan Engine API, you can: * Automate scans by triggering them from CI/CD pipelines, scheduled jobs, or custom workflows * Retrieve findings programmatically and integrate scan results into your tooling * Run headless scans in server-side environments without the user interface * Monitor scans in real-time by polling scan status and acting on results immediately * Cancel scans that are no longer needed * Retrieve findings that have been resolved or fixed over time {#scan-engine-headless-api-overview__ul_ny3_l23_lkc} ## When to use the Scan Engine API {#scan-engine-headless-api-overview__section_when_to_use} Use the Scan Engine API to: * Block deployments based on scan findings and integrate into your CI/CD pipeline to catch issues before code moves to production * Run nightly health checks on your CMDB or service mapping without manual action * Scan multiple applications in parallel as part of a larger automation workflow * Collect and report on scan results over time as part of your monitoring strategy {#scan-engine-headless-api-overview__ul_oy3_l23_lkc} ## Before you start {#scan-engine-headless-api-overview__section_requirements} Requirements: * A ServiceNow instance with Scan Engine enabled, running Impact Platform v12.0.0 or later * A user account with the sn_se.scan_engine_user role * Valid session token or OAuth credentials for authentication * API access enabled on your instance {#scan-engine-headless-api-overview__ul_py3_l23_lkc} ## How the API works {#scan-engine-headless-api-overview__section_how_it_works} The Scan Engine API follows a request-response pattern: {#scan-engine-headless-api-overview__section_how_it_works__entry__2} | Request | Response | |-|-| | Trigger a scan | * Send a POST request to start a scan against an instance, update set, application, or content. * Returns a unique scan result ID you can use to track progress. {#scan-engine-headless-api-overview__ul_jb5_wwg_rkc} | | Check status | Poll the status endpoint to see whether the scan is still running or complete. Returns error and warning counts, and an overall health score. | | Retrieve findings | Once the scan completes, fetch the findings endpoint to get detailed results about what was found and where. | | Act on results | Use the findings in your workflow to fail a CI/CD build, send an alert, or generate a report. | | Cancel scan (optional) | Cancel before the scan completes if it is no longer needed, | | Retrieve resolved findings (optional) | Query for findings that have been fixed or resolved over time to track long-term improvements. | [Table 1. Scan Engine API workflow] ## Key concepts {#scan-engine-headless-api-overview__section_key_concepts} Scan result ID : A unique identifier returned when you start a scan. Use this ID to check status and retrieve findings. It persists in your instance so you can access scan history. Scan mode : The type of scan you're running, either `instance`, `update_set`, `application`, or `content`. Each mode targets a different scope. Suffixed spellings such as `instance_scan` and `application_scan` are also accepted for backward compatibility. The response always echoes the canonical unsuffixed mode name. Health score : A 0--100 score reflecting the overall health of the scanned target. Lower scores indicate more findings. Use this to set thresholds for automated decisions. Findings : Individual violations discovered during a scan. Each finding includes a severity level, a description of the issue, and the affected record. Use findings to prioritize fixes. For a complete list of fields returned in finding responses, see [Scan Engine API field reference](https://www.servicenow.com/docs/cixtE6FmZ4q9Ow6l5mxHmQ "Field reference for scan status, findings, and resolved findings API responses."). Trigger channel : The declared origin of the scan request, either API, UI, or Scheduled. Use this field to determine whether a scan was triggered programmatically. * **[Trigger a scan via API](https://www.servicenow.com/docs/qAB8nzoQXNnlzwWYESH8KQ)** You can start a Scan Engine scan by sending a POST request to the scan endpoint. The API returns a unique scan result ID that you use to check progress and retrieve findings. * **[Check scan status and retrieve findings](https://www.servicenow.com/docs/hHe8xfbg9dcJPW5MxJx_VA)** After triggering a scan, poll the status endpoint to monitor progress and retrieve findings when the scan completes. * **[Automate scans in CI/CD pipelines and scheduled workflows](https://www.servicenow.com/docs/_KVSEbifDtM8mnQLDOK1Iw)** Use the Scan Engine API to automate scans in Continuous Integration/Continuous Deployment (CI/CD) pipelines and scheduled jobs, enabling you to block risky changes or monitor instance health programmatically.