add docs on customizing variability in new apid

docs/latest/api-discovery/exploring.md

@@ -155,17 +155,31 @@ A structured view of session activity helps in understanding your endpoint place
 
 ## Variability
 
-URLs can include diverse elements, such as ID of user. API Discovery supports finding such elements for UUID, INTEGER, FLOAT and HEX path segment types:
+### Path variability
+
+Without unifying variable path segments, the same logical endpoint would appear many times in your inventory—once per distinct value (e.g., one entry per user ID). That would inflate the catalog, make it hard to see your real API surface, and complicate risk analysis and change tracking. API Discovery normalizes these varying segments so you get one endpoint per unique path pattern and can manage and secure your APIs effectively.
+
+These varying segments are diverse elements in URLs, such as user IDs. API Discovery **automatically** detects them for UUID, INTEGER, FLOAT and HEX path segment types. In some specific cases, automatic variability can work on a wider scope of parameter types.
 
 * `/api/users/profile/a1b2c3d4-e5f6-7890-1234-567890abcdef12`
 * `/api/users/profile/f0e9d8c7-b6a5-4321-fedc-ba9876543210`
 * `/api/users/profile/1a2b3c4d-5e6f-7080-9102-34567890fedc`
 
-The **API Discovery** module unifies such elements into the `{parameter_X}` format in the endpoint paths, so for the example above you will not have 3 endpoints, but instead there will be one:
+The module unifies such elements into the `{parameter_X}` format in the endpoint path. For the example above you therefore get one endpoint instead of three:
+
+* `/api/users/profile/{parameter_1}`
+
+Click the endpoint to expand its parameters and see which type (UUID, INTEGER, FLOAT or HEX) was automatically detected for each unified parameter.
+
+In endpoint path string, click the `{parameter_1}` unified path element to review its info. Note that automatically detected variability cannot be disabled or modified.
+
+![API Discovery - variability in path](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-variability-in-path.png)
+
+Besides automatic one, API Discovery provides [custom manual variability](setup.md#custom-manual-variability).
 
-* `/api/articles/author/{parameter_1}`
+### Host variability
 
-Click the endpoint to expand its parameters and view which type was automatically detected for the diverse parameter.
+Besides path variability, API Discovery provides automatic **host variability** as well.
 
 ## Notifications
 

docs/latest/api-discovery/setup.md

@@ -52,6 +52,28 @@ To view the current configuration and perform changes, in Wallarm Console, go to
 
 [See details here →](sensitive-data.md#customizing-sensitive-data-detection)
 
+### Custom manual variability
+
+In addition to [automatic variability](exploring.md#path-variability) (unifying path segments such as UUIDs or numeric IDs into `{parameter_X}`), you can define **custom manual variability**—your own **path patterns** so that API Discovery treats certain URL segments as **variable** and merges them into **one endpoint** in the inventory.
+
+* **What it does**: You define path patterns; API Discovery treats matching URL segments as variable and merges them into a single endpoint.
+* **When to use it**: When your APIs contain path elements where it is not immediately obvious they should be treated as variable (e.g., language codes or region-specific values, like `/website/lang/en_US`, `/website/lang/de_DE`, `/website/lang/fr_FR`) and you want to explicitly control how these are grouped in your inventory. Where variable segments are "obvious" (e.g., UUIDs, numeric IDs), automatic variability will handle them without any manual intervention.
+* **Why**: The catalog stays **concise** and reflects the **real structure** of your API.
+
+How to configure:
+
+* **To merge endpoints:** In **API Discovery**, go to the details of an endpoint with an unmerged (variable) path segment. Mouse over the segment and click **Merge similar endpoints** to create a pattern that unifies them.
+* **To review or split a merged pattern:** In the details of an endpoint with a merged segment, mouse over the merged segment and click **Review similar endpoints**. In the review window, you'll see all endpoints currently grouped by this pattern; if needed, you can break the group apart by clicking **Split to individual endpoints**.
+
+    ![API Discovery - manual variability review](../images/about-wallarm-waf/api-discovery-2.0/api-discovery-manual-variability-review.png)
+
+* **Disabling vs. deletion**: Disabling a pattern (either by turning it off in the list or using **Split to individual endpoints**) only makes the pattern inactive—endpoints will be shown separately again, but the pattern itself remains available and can be re-enabled at any time. However, if you choose to **Delete** a pattern, it is permanently removed and cannot be restored or used again in the future.
+
+* Full list of your custom patterns is always available in **API Discovery** → **Configure** → **Variability**.
+
+    !!! info "Applying changes"
+        Both merge and split take time—changes are reflected in the list within **5 minutes**.
+
 ## Notifications
 
 You can set up API Discovery notifications to be sent to your personal email (the one you use to log in) and to any additional emails: