From 419ab9e4ecc049ba7a8edc0db392d7e9cf777ee4 Mon Sep 17 00:00:00 2001 From: SachinAditya <98205043+SachinAditya@users.noreply.github.com> Date: Sat, 27 Dec 2025 16:15:08 +0530 Subject: [PATCH 01/11] Clarify alertFilter API documentation Expanded the description for the addAlertFilter endpoint to include additional notes and requirements. Signed-off-by: SachinAditya <98205043+SachinAditya@users.noreply.github.com> --- openapi.yaml | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 0f02877..ac5ffcc 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1359,15 +1359,25 @@ paths: description: "" schema: type: "string" - /JSON/alertFilter/action/addAlertFilter/: - get: - description: "Adds a new alert filter for the context with the given ID." - operationId: "alertFilterActionAddAlertFilter" - tags: - - "alertFilter" - responses: - default: - $ref: "#/components/responses/ErrorJson" +/JSON/alertFilter/action/addAlertFilter/: + get: + description: | + Adds a new alert filter for the context with the given ID. + + This filter only applies to alerts raised within the specified context. + + Notes: + - 'contextId' is required and must refer to an existing context. + - 'ruleId' must match the alert rule ID from ZAP. + - Set 'enabled=true' for the filter to take effect. + - Parameters passed via curl must be URL-encoded. + operationId: "alertFilterActionAddAlertFilter" + tags: + - "alertFilter" + responses: + default: + $ref: "#/components/responses/ErrorJson" + parameters: - name: "contextId" in: "query" From 7413e47d8d0e12943096579c7883cd8a6efe724d Mon Sep 17 00:00:00 2001 From: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> Date: Fri, 2 Jan 2026 21:07:55 +0530 Subject: [PATCH 02/11] Add general guidance for using the ZAP API with curl This pull request adds general guidance on using the ZAP API with curl, focusing on common usage details such as parameter encoding, boolean parameters, and typical pitfalls when constructing API requests. The documentation is added at a general level (welcome/introduction), without modifying any generated or endpoint-specific API definitions. This change follows the feedback provided on PR #244 and Issue #88, by keeping endpoint documentation unchanged while improving overall API usability for users interacting with the ZAP API via curl. Signed-off-by: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> --- source/includes/welcome.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/source/includes/welcome.md b/source/includes/welcome.md index 54c76f9..0dc193e 100755 --- a/source/includes/welcome.md +++ b/source/includes/welcome.md @@ -47,13 +47,25 @@ The API documentation is divided into nine main sections. The examples show some usages with the minimal required arguments. However, this is not a reference, and not all APIs nor arguments are shown. View the API catalogue to see all the parameters and scope of each API. - ## Basics on the API Request -ZAP APIs provide access to most of the core features of ZAP such as the active scanner and spider. ZAP API is enabled by default -in the daemon mode and the desktop mode. If you are using ZAP desktop, then the API can be configured by visiting the following screen: +The ZAP API is a REST based API. +It can be accessed via HTTP/HTTPS and supports JSON, XML and other formats. +... + +## Using the ZAP API with curl + +When interacting with the ZAP API using curl, keep the following points in mind: -`Tools -> Options -> API`. +- All parameter values must be URL-encoded. +- Boolean parameters (for example `enabled`) must be explicitly provided. +- Special characters such as `:` or `*` must be URL-encoded. +- API actions generally apply to newly raised alerts, not existing ones. +- Use the appropriate API view endpoints to verify applied changes. + +```bash +curl "http://zap/////?param1=value1¶m2=value2" +``` ![zap_desktop_api](../images/zap_desktop_api.png) From 4a50947b4e8a406bade28ea7f74f6fad49b2eae1 Mon Sep 17 00:00:00 2001 From: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> Date: Fri, 2 Jan 2026 21:11:39 +0530 Subject: [PATCH 03/11] Add general guidance for using the ZAP API with curl This pull request adds general guidance on using the ZAP API with curl, focusing on common usage details such as parameter encoding, boolean parameters, and typical pitfalls when constructing API requests. The documentation is added at a general level (welcome/introduction), without modifying any generated or endpoint-specific API definitions. This change follows the feedback provided on PR #244 and Issue #88, by keeping endpoint documentation unchanged while improving overall API usability for users interacting with the ZAP API via curl. Signed-off-by: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> From 0103c9477acc6ad82f6bcb28abf9243bc074fc13 Mon Sep 17 00:00:00 2001 From: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> Date: Sat, 3 Jan 2026 22:00:34 +0530 Subject: [PATCH 04/11] docs: move curl usage guidance under Access the API This change moves the general curl usage guidance under the "Access the API" section, where the API URL format and access details are already introduced. The content remains general and avoids modifying any generated or endpoint-specific API documentation, following maintainer feedback. This improves the structure and readability of the documentation for users interacting with the ZAP API via curl. Signed-off-by: Sachin Vishwakarma <98205043+SachinAditya@users.noreply.github.com> --- source/includes/welcome.md | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/source/includes/welcome.md b/source/includes/welcome.md index 0dc193e..5cd7a28 100755 --- a/source/includes/welcome.md +++ b/source/includes/welcome.md @@ -53,22 +53,6 @@ The ZAP API is a REST based API. It can be accessed via HTTP/HTTPS and supports JSON, XML and other formats. ... -## Using the ZAP API with curl - -When interacting with the ZAP API using curl, keep the following points in mind: - -- All parameter values must be URL-encoded. -- Boolean parameters (for example `enabled`) must be explicitly provided. -- Special characters such as `:` or `*` must be URL-encoded. -- API actions generally apply to newly raised alerts, not existing ones. -- Use the appropriate API view endpoints to verify applied changes. - -```bash -curl "http://zap/////?param1=value1¶m2=value2" -``` - -![zap_desktop_api](../images/zap_desktop_api.png) - ## Basics on the API Request -The ZAP API is a REST based API. -It can be accessed via HTTP/HTTPS and supports JSON, XML and other formats. -... -