ZAP's API scan imports an API definition (OpenAPI, SOAP or GraphQL), runs an active scan against the URLs it finds, and skips checks that do not suit APIs, such as cross-site scripting. It is useful for broad checks on documented routes, but it does not test authorization logic by itself.
What it does
The zap-api-scan script ships in ZAP's Docker images. According to the project documentation it:
- reads a definition from a local file or a URL, in OpenAPI, SOAP or GraphQL format (GraphQL can take a schema file)
- runs an active scan, tuned for APIs
- adds scripts that raise alerts for HTTP server error responses and for content types not normally associated with APIs
- writes reports in HTML, Markdown, XML and JSON
Useful options
| Need | Option or behaviour |
|---|---|
| Skip active attacks | Safe mode runs a baseline scan instead |
| Override host in a remote spec | The -O option |
| Authenticated scan | Load a context file and name a user defined in it |
| Tune rules | A config file sets each rule to FAIL, WARN, INFO or IGNORE |
| Machine readable result | JSON or XML report |
By default all alerts are treated as warnings. Active rules set to IGNORE are not run, which speeds scans up.
Exit codes for CI
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | At least one FAIL |
| 2 | At least one WARN and no FAILs |
| 3 | Other failure |
That makes it simple to fail a pipeline, as long as you decide which rules are FAIL in your config.
What it will not do for you
The scan sends requests from the definition. It does not know which records belong to which user, so cross user access needs your own tests with seeded data. It does not know your business flows. It will not see routes missing from the spec. Where authentication is needed, you must prepare the user and context. See what OpenAPI driven testing cannot find.
A sensible first run
- Point it at staging with a current spec.
- Start in safe mode to confirm the import works.
- Run the active scan with a test user.
- Review results using a triage order.
- Tune the config, then gate your pipeline.
Related: ZAP baseline vs full vs API scan.
Try it yourself
Click through it at your own pace, or open it full screen. Compare the flow with the options above.
Quick check
Does the API scan test GraphQL?
The documentation lists GraphQL as a supported format, with an optional schema file.
Can it replace manual testing?
No. It covers documented routes and generic checks. Authorization and business logic still need targeted tests.
Safeguard's free scan at gold.safeguard.sh/scan covers dependency risk, which this kind of scan does not.
Sources
Last reviewed: 19 October 2026.
