faq to docs

Author: patriciasantaana

src/content/docs/api-shield/frequently-asked-questions.mdx

@@ -4,69 +4,4 @@ title: FAQ
 structured_data: true
 sidebar:
   order: 8
-
----
-
-## Why are my API endpoints not found by API Discovery?
-
-In most cases, this is due to the system not observing enough valid requests over a continuous period.
-
-API Discovery only looks at requests that satisfy all of the following criteria:
-
-1. Requests must return `2XX` response codes from the edge.
-2. Requests must not come directly from Cloudflare Workers.
-3. At least 500 requests are made to the discovered endpoint within a 10 day period.
-
-Endpoints discovered using session identifiers will be labeled as such in the dashboard. If the endpoints are not discovered through session identifiers, they will be discovered using our machine learning-based [API Discovery](/api-shield/security/api-discovery/).
-
----
-
-## How does Cloudflare calculate the recommended rate limit for my endpoint?
-
-
-Cloudflare uses both the volume and frequency of traffic to guide your recommended rate. We calculate the recommended rate value throughout the day, and the new calculation may equal the existing recommendation due to similar traffic profiles existing on your API. When we recalculate, we look at requests that happened in the last 24 hours.
-
-You can view the `P50`/`95`/`99` of your request count for more details under an endpoint’s expanded view.
-
----
-
-## Will I be able to access an endpoint’s data after I delete it?
-
-No. Cloudflare will stop tracking performance data when you delete an endpoint and its previous data will not be stored. This means that if you save this endpoint again, the metrics will start tracking from the point that you save it.
-
----
-
-### Why do I not receive threshold recommendations for my discovered API endpoints?
-
-Thresholds can only be recommended for endpoints that receive sufficient levels of traffic that meet the following criteria:
-
-- Only requests with the same criteria as API Discovery are considered.
-- If traffic has been erratic or intermittent to this endpoint, the threshold might not show up. Cloudflare needs endpoints to receive sufficient valid traffic in any 24-hour period in the last 7 days or since the initial discovery of the endpoint to make statistically safe threshold suggestions.
-- Cloudflare also requires at least 50 distinct sessions to have accessed the endpoint in any 24-hour period in the last 7 days or since the initial discovery of the endpoint. To detect sessions, you must set up [session identifiers](/api-shield/get-started/#session-identifiers).
-
-If you do not receive threshold recommendations for a discovered endpoint, you will see one of the following error codes:
-
-- `404 response`: Cloudflare has not seen sufficient valid traffic for this zone to generate recommendations.
-- `551 response`: Cloudflare has successfully generated recommendations at some point in the past, but we have not seen sufficient recent valid traffic to provide up-to-date recommendations.
-
----
-
-## Does API Shield work for JDCloud customers?
-
-Not currently.
-
----
-
-## What version of OpenAPI specification do you support?
-
-The importing ([Schema validation](/api-shield/security/schema-validation/)) and exporting ([Schema learning](/api-shield/management-and-monitoring/#endpoint-schema-learning)) of OpenAPI schemas from our product to customers is done using **OpenAPI v3.0**. Any specifications using patched versions (3.0.x) are compatible as well.
-
----
-
-## Why am I not seeing latency metrics?
-
-Latency metrics currently are not supported when a Cloudflare Worker is running on the URL, as the requests are not passed directly to your origin.
-
-Some Cloudflare products such as [Waiting Room](/waiting-room/) are built on top of Workers, so the same limitations apply to applications using these products.
-
-
+---

src/content/docs/api-shield/index.mdx

@@ -11,7 +11,6 @@ head:
 
 import { Description, Feature, Plan, RelatedProduct, Render } from "~/components"
 
-
 <Description>
 Identify and address your API vulnerabilities.
 </Description>
@@ -49,6 +48,10 @@ Cloudflare API Security products are available to Enterprise customers only, tho
 
 The full API Shield security suite is available as an Enterprise-only paid add-on, but all customers can access [Endpoint Management](/api-shield/management-and-monitoring/) and [Schema validation](/api-shield/security/schema-validation/) functionalities.
 
+:::note
+API Shield currently does not work for JDCloud customers.
+:::
+
 ## Related products
 
 <RelatedProduct header="DDoS Protection" href="/ddos-protection/" product="ddos-protection">

src/content/docs/api-shield/management-and-monitoring/endpoint-management/index.mdx

@@ -183,6 +183,10 @@ You can delete endpoints one at a time or in bulk.
   </TabItem>
 </Tabs>
 
+:::caution
+When you delete an endpoint from Endpoint Management, Cloudflare immediately stops tracking all associated performance and analytics data. The endpoint's previous historical metrics are permanently removed and cannot be restored. If you later save this endpoint again, metric tracking will resume, starting from the point the endpoint is re-saved.
+:::
+
 ## Endpoint Analysis
 
 For each saved endpoint, customers can view:
@@ -218,3 +222,14 @@ Once Sensitive Data Detection is enabled for your zone, API Shield queries firew
 API Shield displays the types of sensitive data found if you expand the Endpoint Management table row to view further details. Select **Explore Events** to view the matched events in Security Events.
 
 After Sensitive Data Detection is enabled for your zone, you can [browse the Sensitive Data Detection ruleset](https://dash.cloudflare.com/?to=/:account/:zone/security/data/ruleset/e22d83c647c64a3eae91b71b499d988e/rules). The link will not work if Sensitive Data Detection is not enabled.
+
+## Limitations
+
+Certain performance metrics, such as latency, are not supported when a request is handled by a Cloudflare service in a way that prevents it from being passed directly to your origin server.
+
+This limitation is specifically observed when:
+
+- A Cloudflare Worker is running on the URL path.
+- Other products built on top of Workers, such as [Waiting Room](/waiting-room/), are active on the application.
+
+In these scenarios, the system is unable to accurately measure the origin response time, and the metric will not be populated in the dashboard.

src/content/docs/api-shield/security/api-discovery.mdx

@@ -91,6 +91,18 @@ If all of your zone’s API traffic contains the <GlossaryTooltip term="session
 
 You can direct any feedback about your API Discovery results to your account team.
 
+## Requirements
+
+To ensure your API endpoints are successfully discovered and mapped by Cloudflare, traffic to the endpoint must meet specific operational criteria.
+
+If an endpoint does not appear in the Discovery inbox, it is typically because the system has not observed enough valid requests over a continuous period. API Discovery only processes requests that satisfy all of the following requirements:
+
+- The request must return a `2xx` response code from the Cloudflare edge.
+- The request must not come directly from Cloudflare Workers.
+- The endpoint must receive at least 500 requests within a 10-day period.
+
+Endpoints discovered using session identifiers will be labeled as such in the Cloudflare dashboard. If the endpoints are not discovered through session identifiers, they will be discovered using our machine learning-based [API Discovery](/api-shield/security/api-discovery/).
+
 ## Availability
 
 API Discovery is only available for Enterprise customers. If you are an Enterprise customer and interested in this product, contact your account team.

src/content/docs/api-shield/security/schema-validation/index.mdx

@@ -356,7 +356,13 @@ OpenAPI schemas generated by different tooling may not be specific enough to imp
 
 ## Limitations
 
-Schema validation supports [OpenAPI Version 3.0.x schemas](https://spec.openapis.org/oas/v3.0.3). OpenAPI 3.1 is not supported yet, and we do not plan to expand support for OpenAPI 2.0.
+Cloudflare API Shield's Schema validation (importing) and [Schema learning](/api-shield/management-and-monitoring/endpoint-management/schema-learning/) (exporting) capabilities rely on the [OpenAPI Specification (OAS) v3.0](https://spec.openapis.org/oas/v3.0.3).
+
+This support includes all patch versions, such as OAS v3.0.x. We do not currently support OAS v3.1 and do not plan to expand support for OpenAPI 2.0.
+
+:::note
+Cloudflare recommends using a third-party tool like [Swagger Editor](https://editor.swagger.io/) to ensure that all schemas are fully compliant with the OAS v3.0 specification before upload.
+:::
 
 Currently, API Shield does not support some features of API schemas, including the following: all responses, external references, non-basic path templating, or unique items.
 

src/content/docs/api-shield/security/volumetric-abuse-detection.mdx

@@ -11,8 +11,6 @@ import { GlossaryTooltip, Steps, Render, APIRequest } from "~/components"
 
 Cloudflare Volumetric Abuse Detection helps you set up a system of adaptive rate limiting.
 
-## About
-
 After [API Discovery](/api-shield/security/api-discovery/), Cloudflare looks for <GlossaryTooltip term="API endpoint">endpoint</GlossaryTooltip> abuse based on common user traffic.
 
 For example, your API might see different levels of traffic to a `/reset-password` endpoint than a `/login` endpoint. Additionally, your `/login` endpoint might see higher than average traffic after a successful marketing campaign.
@@ -27,20 +25,38 @@ Volumetric Abuse Detection rate limits are a way to prevent blatant volumetric a
 
 Volumetric Abuse Detection analyzes your API’s individual session traffic statistics to recommend per-endpoint, per-session rate limits.
 
-Volumetric Abuse Detection currently requires a <GlossaryTooltip term="session identifier" link="/api-shield/get-started/#to-set-up-session-identifiers">session identifier</GlossaryTooltip>, like an authorization token available as a request header or cookie.
-
-After adding a session identifier, allow 24 hours for rate limit recommendations to appear on endpoints in the Cloudflare dashboard.
+To access your endpoints: 
 
 Old dashboard: **Security** > **API Shield** > **Endpoint Management**
 
 New dashboard: **Security** > **Web Assets** > **Endpoints**
 
 Recommendations will continue to update if your traffic pattern changes.
 
-### Observe rate limits
+### Requirements
+
+Volumetric Abuse Detection generates rate limit thresholds only after collecting sufficient, statistically safe traffic data for an endpoint. If recommendations are missing for a discovered endpoint, the traffic likely failed to meet the necessary criteria.
+
+Thresholds are suggested only for endpoints that satisfy all of the following requirements within the last seven days (or since initial discovery):
+- The endpoint must receive sufficient valid traffic (traffic that meets the [API Discovery](/api-shield/security/api-discovery/) criteria). Intermittent or erratic traffic may prevent suggestions.
+- The endpoint must be accessed by at least 50 distinct sessions in any 24-hour period.
+- <GlossaryTooltip term="session identifier" link="/api-shield/get-started/#to-set-up-session-identifiers">Session identifiers</GlossaryTooltip>, such as an authorization token available as a request header or cookie, must be configured to allow Cloudflare to accurately detect individual sessions and perform the required per-session rate analysis.
+
+After adding a session identifier, allow 24 hours for rate limit recommendations to appear on endpoints in the Cloudflare dashboard.
+
+If recommendations fail to generate, one of the following response codes may appear in the Cloudflare dashboard:
+
+| Error code | Description |
+| --- | --- |
+| `404 response` | Cloudflare has not seen sufficient valid traffic for this zone to generate initial recommendations. |
+| `551 response` | Cloudflare previously generated recommendations, but we have not seen sufficient recent valid traffic to provide up-to-date suggestions. |
+
+### Rate limiting recommendation calculation 
 
 Once rate limit recommendations appear in **Endpoints**, select the endpoint row to view more detail about the recommendation. You will see the overall recommended rate limit value, as well as p99, p90, and p50 rate limit values.
 
+We calculate the recommended rate limit value throughout the day, and the new calculation may equal the existing recommendation due to similar traffic profiles existing on your API. When we recalculate, we look at requests that happened in the last 24 hours.
+
 Cloudflare recommends choosing the overall rate limit recommendation, as our analysis includes the variance of the request rate distribution across your API sessions. Choosing a single p-value may cause false positives due to a high number of outliers.
 
 :::note[p-values]
@@ -56,6 +72,7 @@ Implementing low confidence rate limits can still be helpful to prevent API abus
 
 Refer to the [Rules documentation](https://developers.cloudflare.com/waf/rate-limiting-rules/create-zone-dashboard/) for more information on how to create an Advanced Rate Limiting rule.
 
+
 ## API
 
 [Rate limit recommendations are available via the API](/api/resources/api_gateway/subresources/operations/methods/get/) if you would like to dynamically update rate limits over time.