This API enables extensions to obtain information about and modify declarative rules that block or modify network requests. The use of declarative rules means that extensions don't intercept and view the content of requests, providing more privacy.


To use this API, an extension must request the "declarativeNetRequest" or "declarativeNetRequestWithHostAccess" permissions in its manifest.json file.

The "declarativeNetRequest" permission allows extensions to block and upgrade requests without any host permissions. Host permissions are required if the extension wants to redirect a request or modify headers on a request. The "declarativeNetRequestWithHostAccess" permission requires host permissions to the request URL and initiator to act on a request.

The "declarativeNetRequestFeedback" permission is required to use getMatchedRules and onRuleMatchedDebug as they return information on declarative rules matched. See Testing for more information.


The declarative rules are defined by four fields:

  • id – An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1.
  • priority – The rule priority. When specified, it should be >= 1. Defaults to 1. See Matching precedents for details on how priority affects which rules are applied.
  • condition – The condition under which this rule is triggered.
  • action – The action to take when the rule is matched. Rules can do one of these things:
    • block a network request.
    • redirect a network request.
    • modify headers from a network request.
    • prevent another matching rule from being applied.

This is an example rule that blocks all script requests originating from "" to any URL with "abc" as a substring:

  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : 
    "urlFilter" : "abc",
    "domains" : [""],
    "resourceTypes" : ["script"]

The urlFilter field of a rule condition is used to specify the pattern matched against the request URL. See RuleCondition for details. Some examples of URL filters are:

urlFilter Matches Does not match


Rules are organized into rulesets:

  • static rulesets: collections of rules defined with the "declarative_net_request" manifest key and stored in the extension. An extension can enable and disable static rulesets using updateEnabledRulesets. The set of enabled static rulesets is persisted across sessions but not across extension updates. The static rulesets enabled on extension installation and update are determined by the content of the "declarative_net_request" manifest key.
  • dynamic ruleset: rules added or removed using updateDynamicRules. These rules persist across sessions and extension updates.
  • session ruleset: rules added or removed using updateSessionRules. These rules do not persist across browser sessions.

Note: Errors and warnings about invalid static rules are only displayed during testing. Invalid static rules in permanently installed extensions are ignored. Therefore, it's important to verify that your static rulesets are valid by testing.


Static ruleset limits

An extension can:

Dynamic and session-scoped rules

The number of dynamic and session-scoped rules an extension can add is limited to the value of MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Matching precedents

When the browser evaluates how to handle requests, it checks each extension's rules that have a condition that matches the request and chooses the one to consider applying as follows:

  1. the rule priority, where 1 is the lowest priority (and rules default to 1 where priority is not set) If this doesn't result in one rule to apply:
  2. the rule action, in the following order of precedence:
    1. "allow" which means any other remaining rules are ignored.
    2. "allowAllRequests" (for main_frame and sub_frame resourceTypes only) has the same effect as allow but also applies to future subresource loads in the document (including descendant frames) generated from the request.
    3. "block" cancels the request.
    4. "upgradeScheme" upgrades the scheme of the request.
    5. "redirect" redirects the request.
    6. "modifyHeaders" rewrites request and response headers. If this doesn't result in one rule to apply:
  3. the ruleset the rule belongs to, in this order of precedence:
    1. session
    2. dynamic
    3. static If this doesn't result in one rule to apply:
  4. the order of the rule in the ruleset, determined as the lowest value rule ID.

If only one extension provides a rule for the request, that rule is applied. However, where more than one extension has a matching rule, the browser chooses the one to apply in this order of precedence:

  1. "block"
  2. "redirect" and "upgradeScheme"
  3. "allow" and "allowAllRequests"

If the request was not blocked or redirected, the matching modifyHeaders actions are applied, as documented in declarativeNetRequest.ModifyHeaderInfo.


testMatchOutcome, getmatchedrules, and onRuleMatchedDebug are available to assist with testing rules and rulesets. These APIs require the "declarativeNetRequestFeedback" permissions. In addition:

  • in Chrome, these APIs are only available to unpacked extensions.
  • in Firefox, these APIs are only available after setting the preference to true. Set this preference using about:config or the --pref flag of the web-ext CLI tool.

Comparison with the webRequest API

  • The declarativeNetRequest API evaluates network requests in the browser itself. This makes it more performant than the webRequest API, where each network request is evaluated in JavaScript in the extension process.
  • Because the requests are not intercepted by the extension process, declarativeNetRequest removes the need for extensions to have a background page.
  • Unlike the webRequest API, blocking or upgrading requests using the declarativeNetRequest API requires no host permissions when used with the declarativeNetRequest permission.
  • The declarativeNetRequest API provides better privacy to users because extensions do not read the network requests made on the user's behalf.
  • (Chrome only:) Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM.
  • While deciding whether a request is to be blocked or redirected, the declarativeNetRequest API is given priority over the webRequest API because it allows for synchronous interception. Similarly, any headers removed through declarativeNetRequest API are not made visible to web request extensions.
  • The webRequest API is more flexible than the declarativeNetRequest API because it allows extensions to evaluate a request programmatically.



Details of a matched rule.


The request or response headers to modify for the request.


Details of how the redirect should be performed. Only valid for redirect rules.


The resource type of a request.


An object containing details of a rule.


An object defining the action to take if a rule is matched.


An object defining the condition under which a rule is triggered.


An object containing details of a URL transformation to perform for a redirect action.



Ruleset ID for the dynamic rules added by the extension.


The time interval within which declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL declarativeNetRequest.getMatchedRules calls can be made.


The minimum number of static rules guaranteed to an extension across its enabled static rulesets.


The number of times declarativeNetRequest.getMatchedRules can be called within a period of declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL.


The maximum number of combined dynamic and session scoped rules an extension can add.


The maximum number of static rulesets an extension can enable.


The maximum number of regular expression rules that an extension can add.


The maximum number of static rulesets an extension can specify as part of the declarative_net_request.rule_resources manifest key.


The ruleset ID for the session-scoped rules added by the extension.



Returns the number of static rules an extension can enable before the global static rule limit is reached.


Returns the set of dynamic rules for the extension.


Returns the IDs for the set of enabled static rulesets.


Returns all the rules matched for the extension.


Returns the set of session scoped rules for the extension.


Checks if a regular expression is supported as a declarativeNetRequest.RuleCondition.regexFilter rule condition.


Configures how the action count for tabs are handled.


Checks if any of the extension's declarativeNetRequest rules would match a hypothetical request.


Modifies the active set of dynamic rules for the extension.


Updates the set of active static rulesets for the extension.


Modifies the set of session scoped rules for the extension.



Fired when a rule is matched with a request when debugging an extension with the "declarativeNetRequestFeedback" permission.

Browser compatibility

BCD tables only load in the browser