Manage operations

Each operation has one of the following states:

You do not need to promote every discovered operation to the full state. Candidate operations provide operation context automatically, while full operations support additional learning and protections.

If an operation does not appear in Web Assets, Cloudflare may not have observed enough valid requests over a continuous period. 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 operation must receive at least 500 requests within a 10-day period.

Discovery continuously identifies operations from proxied HTTP traffic. Discovery groups similar request paths together by using path normalization.

For example, discovery can group these requests:

GET https://api.example.com/profile/238
GET https://api.example.com/profile/392

Discovery can group them into one operation:

GET api.example.com/profile/{var1}

Discovered operations are used for matching before you manually refine them. This provides operation context for discovered traffic without requiring you to promote every discovery first.

Discovery-backed matching is subject to plan availability and system limits. Cloudflare currently sends up to 3,000 operations per zone to the edge for matching. Operations in the full state are prioritized first, followed by operations in the candidate state.

Promote a candidate or shadow operation to move it into the full state and start profile learning.

The Learn profile action is available to API Shield customers using unified operation discovery and other customers with access to profile learning.

After promotion, Cloudflare learns the expected request structure from observed traffic. For API endpoints, API Shield also collects data to learn and report additional context:

• Request structures through schema learning
• Normal request volume through rate limit recommendations
• Authentication usage through Authentication Posture
• Persisted security findings through API endpoint risk labels

Each feature has separate data and timing requirements. For example, schema learning requires an operation to remain full for at least 24 hours.

Full operations can also use protections that require a known API endpoint, including Schema Validation, fallthrough rules, and sequence mitigation.

After promotion, the row action changes to Profile learned.

Cloudflare matches each request to one operation at the edge. When more than one operation pattern could match the same request, the more specific operation wins.

For example, these operations could both match GET https://example.com/checkout/pay:

GET example.com/checkout/pay
GET example.com/checkout/{var1}

Cloudflare uses GET example.com/checkout/pay because it is more specific.

For the same method, hostname pattern, and path pattern, Cloudflare generates the same operation UUID. This keeps operation identity stable when the same operation is found again.

Add an operation manually when traffic you want to protect has not been discovered, or when you want to define the operation structure yourself.

When you add an operation manually, use variables to match similar traffic with one operation.

For path variables, enclose the variable in braces:

/api/users/{var1}/details

For hostname variables, the variable must occupy a complete hostname label. Cloudflare supports patterns such as:

{hostVar1}.example.com
foo.{hostVar1}.example.com
{hostVar2}.{hostVar1}.example.com

Do not combine a hostname variable with other characters in the same label. The following pattern is not supported:

foo-{hostVar1}.example.com

If you already maintain OpenAPI schemas, you can continue uploading them to create operations.

Schema upload is also used by API Shield for schema validation. For more information, refer to Schema Validation and schema learning.

Refine operations when the current grouping does not match how the traffic should be grouped or protected.

For example, you may want separate operations for login and password reset traffic, even if both routes share part of the same path structure. You may also want to replace several narrow operations with one broader operation when they represent the same application behavior.

Review overlapping operations before making changes. Cloudflare matches a request to one operation. A broad operation can change how similar requests are grouped, while a narrow operation can isolate one flow from related traffic.

Editing a candidate or shadow operation promotes it to the full state with the edited values.

You can delete operations one at a time or in bulk.

You can interact with operations through the Cloudflare API. For more information, refer to operations API documentation.