Create a policy
Get an API key in the Quickstart. Name the policy, then list domains. This one is an allowlist: it blocks everything exceptexample.com and bun.com.
defaultAction out, which means allow, and list the sites in block.domains. A domain such as example.com covers itself and every subdomain. When two entries match, the most specific wins. Domains are trimmed, lower-cased and de-duplicated, and a leading *. is dropped.
Apply it to a session
Send the policyid as networkPolicyId when you open the session.
networkPolicyId and networkPolicyVersion, the version of the policy the session enforces now. Visit one allowed site and one blocked site with Execute:
result:
allowedDomains instead, up to 100 domains. Only those domains load. It cannot be sent with networkPolicyId.
Change a running session
PATCH /v1/browser/network-policies/{policy_id} changes the policy and every running session that uses it. Each field you send replaces the old one, and a list replaces the whole list. This adds example.org:
appliedSessions is 1 and the session now shows networkPolicyVersion 2. The same visit then returned Example Domain for both sites. A session the call could not reach is in pendingSessionIds, and the change is retried every few seconds until it arrives. A session behind the policy’s version has not received the change yet. When a change blocks a host, open connections to it are closed, and closedConnections counts them.
Manage policies
Options
Limits and errors
- A policy holds at most 10,000 domains in
allowandblocktogether, and an account at most 100 policies. - A URL, a path, a port, an IP address, another wildcard, or a domain in both lists returns
400 invalidRequest. A real answer for a URL:allow.domains.0: "https://example.com/page": Expected a domain such as example.com. It covers its subdomains too. A leading *. is allowed. URLs, paths, ports, IP addresses and other wildcards are not. - Deleting a policy that a running session uses returns
409 invalidRequest:1 running browser session uses this policy. Close it or wait for it to end, then delete the policy. - An unknown policy id returns
404 notFound.
Related
- Browser sessions opens the session that uses the policy.
- Network location chooses the country a session appears in.
- Policy reference lists every field.