API
Start typing to search…

Create a rate policy

post https://{hostname}/appsec/v1/configs//versions//rate-policies

All products Create a new rate policy for a specific configuration version. Now you can match on defined or undefined resources. If you're setting a match for either resource type, both definedResources and undefinedResources must be present in the request object or the request is considered incomplete. When true, match on any defined resources without passing a resourceId. When false, you'll need to pass a resourceId. If you pass definedResources and undefinedResources with empty values, they default to false. You can omit both resources and use this operation without these new match criteria. Contact your account team if you'd like to match on definedResources or undefinedResources.

Path Params
int64
required

A unique identifier for each configuration.

integer
required

A unique identifier for each version of a configuration.

Query Params
string

For customers who manage more than one account, this runs the operation from another account. The Identity and Access Management API provides a list of available account switch keys.

Body Params
additionalMatchOptions
array of objects

The list of additional match conditions.

additionalMatchOptions
apiSelectors
array of objects

The API endpoints to match in incoming requests. This only applies to the api matchType.

apiSelectors
integer
required
≥ 1

The allowed hits per second during any two-minute interval.

bodyParameters
array of objects

The list of body parameters to match on.

bodyParameters
integer
required
≥ 1

The allowed hits per second during any five-second interval.

integer
1 to 5

The time span for the burstThreshold interval. For existing rate policies, analyze your traffic in Alert mode before you reduce the measure window from 5 seconds. Learn more about thresholds here.

string
required
length ≥ 0

Deprecated The client identifier you want to use to identify and track request senders. The value is required only for WAF type, and api-key is supported only for API match criteria. Using ip-useragent is typically more specific than using ip alone when trying to identify a client. Tracking by cookie:value applies to requests per individual session, even if the IP address changes. This field will be removed in future releases. Use clientIdentifiers instead.

clientIdentifiers
array of strings
length ≥ 0

Client identifiers to track request senders. The value is required only for WAF type, and api-key is supported only for API match criteria. Using ip-useragent is typically more specific than using ip alone when trying to identify a client. Tracking by cookie:value applies to requests per individual session, even if the IP address changes.

clientIdentifiers
condition
object

Contains information about the criteria that trigger the rate policy.

string
Defaults to per_edge

The rate policy counter type. Either per_edge for rate limiting to work per edge node, or region_aggregated for rate limiting to work using aggregated rate accounting across multiple edge nodes.

string

Descriptive text you provide about a policy.

evaluation
object

Contains details about rate policy evaluation.

fileExtensions
object

Contains the file extension match criteria.

hostnames
array of strings

Deprecated. The hostnames to match. This array member is deprecated. Use the hosts object instead.

hostnames
hosts
object

The hostnames to match, and whether to trigger on a match or absence of match.

string
required

The match type in a rate policy. Either path to match website paths or api to match API paths.

string
required

The name you assign to a rate policy.

path
object

Contains details about the path match criteria.

string
required

The type of paths to match in incoming requests. Either AllRequests to match an empty path or any path that ends in a trailing slash (/), TopLevel to match top-level hostnames only, or Custom to match a specific path or path component. This applies only when the corresponding matchType member is path.

boolean

Whether the condition should trigger on a match (true) or a lack of match (false).

queryParameters
array of objects

The list of query parameter objects to match on.

queryParameters
string
required

The type of requests to count towards the rate policy's thresholds. Either ClientRequest to count client requests to edge servers, ClientResponse to count edge responses to the client, ForwardResponse to count origin responses to the client, or ForwardRequest to count edge requests to your origin.

boolean
required

Whether to apply the same action to the IPv6 traffic as to the IPv4 traffic.

string
required

The rate policy type. Either WAF for Web Application Firewall, or BOTMAN for Bot Manager.

boolean

Whether to check the contents of the X-Forwarded-For header in incoming requests.

Responses

Response body
object
additionalMatchOptions
array of objects

The list of additional match conditions.

additionalMatchOptions
object
boolean
required

Whether the condition should trigger on a match (true) or a lack of match (false).

string
required

The match condition type. The RequestHeaderCondition listed here is deprecated. Specify RequestHeaderCondition as an atomicCondition to match on request headers. See Export match condition type values.

IpAddressCondition NetworkListCondition RequestHeaderCondition RequestMethodCondition ResponseHeaderCondition ResponseStatusCondition UserAgentCondition AsNumberCondition

values
array of strings
required

The list of values that trigger the condition on match.

values*
apiSelectors
array of objects

The API endpoints to match in incoming requests. This only applies to the api matchType.

apiSelectors
object
integer
required

Uniquely identifies each API endpoint.

boolean

When true, match on any resource explicitly added to your API definition without including a resourceId. When false, you'll need to pass a resourceId.

resourceIds
array of integers

The unique identifiers of the endpoint's resources.

resourceIds
boolean

When true, match on any resource you have not explicitly added to your API definition without including a resourceId. When false, you'll need to pass a resourceId.

integer
required
≥ 1

The allowed hits per second during any two-minute interval.

bodyParameters
array of objects

The list of body parameters to match on.

bodyParameters
object
string
required

The name you assign to a body parameter.

boolean
required

Whether the condition should trigger on a match (true) or a lack of match (false).

boolean

Whether to match a value inside or outside a range. The range format is min:max — for example, 2:4.

values
array of strings
required

The body parameter values.

values*
integer
required
≥ 1

The allowed hits per second during any five-second interval.

integer
1 to 5

The time span for the burstThreshold interval. For existing rate policies, analyze your traffic in Alert mode before you reduce the measure window from 5 seconds. Learn more about thresholds here.

string
required
length ≥ 0

Deprecated The client identifier you want to use to identify and track request senders. The value is required only for WAF type, and api-key is supported only for API match criteria. Using ip-useragent is typically more specific than using ip alone when trying to identify a client. Tracking by cookie:value applies to requests per individual session, even if the IP address changes. This field will be removed in future releases. Use clientIdentifiers instead.

api-key ip-useragent ip cookie:value

clientIdentifiers
array of strings
length ≥ 0

Client identifiers to track request senders. The value is required only for WAF type, and api-key is supported only for API match criteria. Using ip-useragent is typically more specific than using ip alone when trying to identify a client. Tracking by cookie:value applies to requests per individual session, even if the IP address changes.

clientIdentifiers
condition
object

Contains information about the criteria that trigger the rate policy.

atomicConditions
array
length ≥ 1

The conditions that trigger the rate policy. Specify one or more request headers, TLS fingerprints, or client reputation categories.

atomicConditions
boolean

Whether the condition should trigger on a match (true) or a lack of match (false).

string
Defaults to per_edge

The rate policy counter type. Either per_edge for rate limiting to work per edge node, or region_aggregated for rate limiting to work using aggregated rate accounting across multiple edge nodes.

per_edge region_aggregated

date-time

Read-only The time stamp when you created the rate policy.

string

Descriptive text you provide about a policy.

evaluation
object

Contains details about rate policy evaluation.

integer
required
≥ 1

The allowed hits per second during any two-minute interval during evaluation.

integer
required
≥ 1

The allowed hits per second during any five-second interval during evaluation.

integer

Read-only The time span for the burstThreshold interval used during evaluation. This value is always set to the burstWindow specified by the main rate policy.

string
Defaults to region_aggregated

The evaluation rate policy counter type. Either per_edge for rate limiting to work per edge node, or region_aggregated for rate limiting to work using aggregated rate accounting across multiple edge nodes.

per_edge region_aggregated

date-time

Read-only The time stamp when evaluation ends.

integer

Read-only Uniquely identifies an evaluation.

string

Read-only Reflects evaluation status, either in_progress, pending_activation, or completed.

in_progress pending_activation completed

date-time

Read-only The time stamp when evaluation starts.

integer

Read-only Evaluation version.

fileExtensions
object

Contains the file extension match criteria.

boolean
required

Whether the condition should trigger on a match (true) or a lack of match (false).

values
array of strings
required

The file extensions to match on.

values*
hostnames
array of strings

Deprecated. The hostnames to match. This array member is deprecated. Use the hosts object instead.

hostnames
hosts
object

The hostnames to match, and whether to trigger on a match or absence of match.

boolean
required
Defaults to true

When true, triggers on hostnames that match any hostnames in this array. When false, triggers on hostnames that don't match any in this array.

values
array of strings
required

The hostnames you choose to match, or specifically not match.

values*
integer

Read-only Uniquely identifies each rate policy.

string
required

The match type in a rate policy. Either path to match website paths or api to match API paths.

path api

string
required

The name you assign to a rate policy.

path
object

Contains details about the path match criteria.

boolean
required

Whether the condition should trigger on a match (true) or a lack of match (false).

values
array of strings
required

The list of paths to match on.

values*
string
required

The type of paths to match in incoming requests. Either AllRequests to match an empty path or any path that ends in a trailing slash (/), TopLevel to match top-level hostnames only, or Custom to match a specific path or path component. This applies only when the corresponding matchType member is path.

AllRequests TopLevel Custom

boolean

Whether the condition should trigger on a match (true) or a lack of match (false).

queryParameters
array of objects

The list of query parameter objects to match on.

queryParameters
object
string
required

The query parameter name.

boolean
required

Whether the condition should trigger on a match (true) or a lack of match (false).

boolean

Whether to match a value inside or outside a range. The range format is min:max — for example, 2:4.

values
array of strings
required

The list of query parameter values.

values*
string
required

The type of requests to count towards the rate policy's thresholds. Either ClientRequest to count client requests to edge servers, ClientResponse to count edge responses to the client, ForwardResponse to count origin responses to the client, or ForwardRequest to count edge requests to your origin.

ClientRequest ClientResponse ForwardResponse ForwardRequest

boolean
required

Whether to apply the same action to the IPv6 traffic as to the IPv4 traffic.

string
required

The rate policy type. Either WAF for Web Application Firewall, or BOTMAN for Bot Manager.

WAF BOTMAN

date-time

Read-only The ISO 8601 timestamp when you last updated the rate policy.

boolean

Whether to check the contents of the X-Forwarded-For header in incoming requests.

boolean

Read-only Whether you're currently using the rate policy.

Updated 10 days ago

Did this page help you?
Language
Authentication
Remember to add your authentication credentials to run this code.
URL

Updated 10 days ago

Did this page help you?