add examples and info for the asset policy and misconfig APIs

api-reference/assets/create-asset-policy.mdx

@@ -1,3 +1,75 @@
 ---
 openapi: post /v1/asset/policy
 ---
+
+<Note>
+The `policy_type` determines which fields are required:
+
+| Policy Type | Required Fields |
+|---|---|
+| `alert` (default) | `alerting_config_ids` |
+| `delete` | — |
+| `set_label` | `labels` |
+| `remove_label` | `labels` |
+
+**Conditions:** Multiple filters in the `policies` object use AND logic — all conditions must match for the policy to apply.
+
+**Scope:** Set `apply_to_existing` to `true` to apply the policy to existing matching assets immediately. When `false` (default), the policy only acts on newly discovered assets.
+</Note>
+
+## Example Requests
+
+### Create a delete policy for noisy assets
+
+```bash
+curl -X POST "https://api.projectdiscovery.io/v1/asset/policy" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Remove 401 webhooks",
+    "policy_type": "delete",
+    "policies": {
+      "host": "www.webhook.office.com",
+      "status_code": "401"
+    },
+    "apply_to_existing": true
+  }'
+```
+
+### Create an alert policy for sensitive ports
+
+```bash
+curl -X POST "https://api.projectdiscovery.io/v1/asset/policy" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Alert on sensitive ports",
+    "policy_type": "alert",
+    "policies": {
+      "port": "22,3306,5432,6379"
+    },
+    "alerting_config_ids": ["your-alerting-config-id"],
+    "apply_to_existing": false
+  }'
+```
+
+### Create a labeling policy
+
+```bash
+curl -X POST "https://api.projectdiscovery.io/v1/asset/policy" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Tag WordPress sites",
+    "policy_type": "set_label",
+    "policies": {
+      "technologies": "WordPress"
+    },
+    "labels": ["cms", "wordpress"],
+    "apply_to_existing": true
+  }'
+```
+
+## Related Resources
+
+- [Asset Policies Guide](/cloud/assets/asset-policies) - Feature overview with walkthrough

api-reference/assets/get-asset-policy-events.mdx

@@ -1,3 +1,10 @@
 ---
 openapi: get /v1/asset/policy/{policy_id}/events
 ---
+
+## Example Request
+
+```bash
+curl -X GET "https://api.projectdiscovery.io/v1/asset/policy/POLICY_ID/events?limit=20&offset=0" \
+  -H "X-Api-Key: YOUR_API_KEY"
+```

api-reference/assets/get-asset-policy-suggestions.mdx

@@ -1,3 +1,18 @@
 ---
 openapi: get /v1/asset/policy/suggestion
 ---
+
+<Note>
+Each suggestion includes a pre-built policy template that can be used directly with the Create Asset Policy endpoint.
+
+**Categories analyzed:** error status codes, zero content length, TLS issues, sensitive ports, IP concentration, repeated titles, sensitive technologies (Jenkins, Kubernetes, Redis, etc.), admin panels, login pages, and dev/staging environments.
+
+The `threshold` parameter controls the minimum percentage of assets a pattern must affect to be suggested (default: 5%).
+</Note>
+
+## Example Request
+
+```bash
+curl -X GET "https://api.projectdiscovery.io/v1/asset/policy/suggestion?limit=5&threshold=10" \
+  -H "X-Api-Key: YOUR_API_KEY"
+```

api-reference/assets/get-asset-policy.mdx

@@ -1,3 +1,7 @@
 ---
 openapi: get /v1/asset/policy/{policy_id}
 ---
+
+## Related Resources
+
+- [Asset Policies Guide](/cloud/assets/asset-policies) - Feature overview with UI walkthrough

api-reference/assets/list-asset-policies.mdx

@@ -1,3 +1,7 @@
 ---
 openapi: get /v1/asset/policy
 ---
+
+## Related Resources
+
+- [Asset Policies Guide](/cloud/assets/asset-policies) - Feature overview with UI walkthrough

api-reference/assets/update-asset-policy.mdx

@@ -1,3 +1,43 @@
 ---
 openapi: patch /v1/asset/policy/{policy_id}
 ---
+
+<Note>
+The `update_type` query parameter controls how values are merged:
+
+| Mode | Behavior |
+|---|---|
+| `append` (default) | Merges new values with existing ones. For example, adding new `alerting_config_ids` keeps the current ones. |
+| `replace` | Completely overwrites the policy. All required fields for the policy type must be provided. |
+
+In `replace` mode, `alerting_config_ids` is required for `alert` policies and `labels` is required for `set_label`/`remove_label` policies.
+</Note>
+
+## Example Requests
+
+### Append new labels to an existing policy
+
+```bash
+curl -X PATCH "https://api.projectdiscovery.io/v1/asset/policy/POLICY_ID?update_type=append" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "labels": ["new-label"]
+  }'
+```
+
+### Replace policy conditions entirely
+
+```bash
+curl -X PATCH "https://api.projectdiscovery.io/v1/asset/policy/POLICY_ID?update_type=replace" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Updated policy",
+    "policy_type": "delete",
+    "policies": {
+      "host": "staging.example.com",
+      "status_code": "503"
+    }
+  }'
+```

api-reference/enumerations/list-enumeration-misconfigurations.mdx

@@ -1,3 +1,51 @@
 ---
 openapi: get /v1/asset/enumerate/misconfiguration
 ---
+
+## Finding Types
+
+| Type | Description |
+|---|---|
+| `dangling_dns` | DNS records pointing to resources that no longer exist, potentially vulnerable to subdomain takeover |
+| `origin_exposure` | Backend origin IPs exposed behind CDN or proxy services |
+
+### Event Details by Finding Type
+
+The `event` object contains type-specific details:
+
+**`dangling_dns`**
+| Field | Description |
+|---|---|
+| `host` | The vulnerable hostname |
+| `ip` | The dangling IP address |
+| `provider` | Cloud provider (e.g., AWS) |
+
+**`origin_exposure`**
+| Field | Description |
+|---|---|
+| `origin_ip` | The exposed origin server IP |
+| `provider` | CDN provider (e.g., CloudFlare) |
+| `leaking_hosts` | Hostnames leaking the origin IP |
+
+## Example Requests
+
+### List all misconfigurations
+
+```bash
+curl -X GET "https://api.projectdiscovery.io/v1/asset/enumerate/misconfiguration?limit=50" \
+  -H "X-Api-Key: YOUR_API_KEY"
+```
+
+### Filter by finding type
+
+```bash
+curl -X GET "https://api.projectdiscovery.io/v1/asset/enumerate/misconfiguration?finding_type=dangling_dns" \
+  -H "X-Api-Key: YOUR_API_KEY"
+```
+
+### Search by host
+
+```bash
+curl -X GET "https://api.projectdiscovery.io/v1/asset/enumerate/misconfiguration?search=staging.example.com" \
+  -H "X-Api-Key: YOUR_API_KEY"
+```