> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Network policies

> Save a list of domains a browser session may reach or may not, apply it when you open sessions, and change it while they run. Free to create and edit.

A network policy is a saved list of domains. A session opened with a policy can reach only what the policy allows. Edit the policy and every running session that uses it follows within seconds. Policies cost nothing.

## Create a policy

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). Name the policy, then list domains. This one is an allowlist: it blocks everything except `example.com` and `bun.com`.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/browser/network-policies \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-only",
    "defaultAction": "block",
    "allow": { "domains": ["example.com", "bun.com"] }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch(
  "https://api.stophy.dev/v1/browser/network-policies",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "docs-only",
      defaultAction: "block",
      allow: { domains: ["example.com", "bun.com"] },
    }),
  },
);
const policy = await response.json();
console.log(policy.id, policy.version);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/browser/network-policies",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "name": "docs-only",
        "defaultAction": "block",
        "allow": {"domains": ["example.com", "bun.com"]},
    },
)
policy = response.json()
print(policy["id"], policy["version"])
```

```json theme={null}
{
  "success": true,
  "id": "749ba63d-2652-46bf-9d79-7c98bf694f1d",
  "name": "docs-only",
  "defaultAction": "block",
  "allow": { "domains": ["example.com", "bun.com"] },
  "block": { "domains": [] },
  "version": 1,
  "createdAt": "2026-11-17T18:18:49.264Z",
  "updatedAt": "2026-11-17T18:18:49.264Z",
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "0c517caf-d041-4e41-a095-b0223c33b3b8"
}
```

To block a few sites and allow the rest, leave `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 policy `id` as `networkPolicyId` when you open the session.

```json theme={null}
{
  "ttl": 300,
  "activityTtl": 60,
  "networkPolicyId": "749ba63d-2652-46bf-9d79-7c98bf694f1d"
}
```

The session answer shows `networkPolicyId` and `networkPolicyVersion`, the version of the policy the session enforces now. Visit one allowed site and one blocked site with [Execute](https://docs.stophy.dev/browser/execute.md):

```json theme={null}
{
  "code": "const visit = async (url) => { try { await page.goto(url, { timeout: 15000 }); return await page.title(); } catch (error) { return String(error).split('\\n')[0]; } };\nreturn { allowed: await visit('https://example.com'), blocked: await visit('https://example.org') };"
}
```

The real `result`:

```json theme={null}
{
  "allowed": "Example Domain",
  "blocked": "Error: goto: net::ERR_TUNNEL_CONNECTION_FAILED at https://example.org/"
}
```

A blocked domain fails to connect, so the page does not load. Blocks apply to every request the session makes, not only to the address you open.

For a short list that belongs to one session, send `allowedDomains` instead, up to 100 domains. Only those domains load. It cannot be sent with `networkPolicyId`.

```json theme={null}
{
  "ttl": 120,
  "activityTtl": 30,
  "allowedDomains": ["example.com"]
}
```

## 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`:

```bash cURL theme={null}
POLICY_ID="<the id your policy returned>"
curl -X PATCH https://api.stophy.dev/v1/browser/network-policies/$POLICY_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow": { "domains": ["example.com", "bun.com", "example.org"] }
  }'
```

```typescript TypeScript theme={null}
const policyId = "<the id your policy returned>";
const response = await fetch(
  `https://api.stophy.dev/v1/browser/network-policies/${policyId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      allow: { domains: ["example.com", "bun.com", "example.org"] },
    }),
  },
);
const changed = await response.json();
console.log(changed.version, changed.appliedSessions, changed.pendingSessionIds);
```

```python Python theme={null}
import os

import requests

policy_id = "<the id your policy returned>"
response = requests.patch(
    f"https://api.stophy.dev/v1/browser/network-policies/{policy_id}",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"allow": {"domains": ["example.com", "bun.com", "example.org"]}},
)
changed = response.json()
print(changed["version"], changed["appliedSessions"], changed["pendingSessionIds"])
```

```json theme={null}
{
  "success": true,
  "id": "749ba63d-2652-46bf-9d79-7c98bf694f1d",
  "name": "docs-only",
  "defaultAction": "block",
  "allow": { "domains": ["example.com", "bun.com", "example.org"] },
  "block": { "domains": [] },
  "version": 2,
  "updatedAt": "2026-11-17T18:19:01.777Z",
  "runningSessions": 1,
  "appliedSessions": 1,
  "pendingSessionIds": [],
  "closedConnections": 0,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "1ea94feb-e66a-4982-b270-5e746800432d"
}
```

The change reached the running session before the call answered: `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

| Action | Call | Notes |
| - | - | - |
| Create | `POST /v1/browser/network-policies` | Free. |
| List | `GET /v1/browser/network-policies` | Newest first. `pageSize` 1 to 100, default 10. `pageNumber` from 1. |
| Read | `GET /v1/browser/network-policies/{policy_id}` | One policy. |
| Change | `PATCH /v1/browser/network-policies/{policy_id}` | Raises `version` by 1. |
| Delete | `DELETE /v1/browser/network-policies/{policy_id}` | Only when no running session uses it. |

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `name` | `string` | none | 1 to 100 characters. Required to create. |
| `defaultAction` | `string` | `allow` | What happens to a domain no entry matches: `allow` or `block`. Send `block` with `allow.domains` for an allowlist. |
| `allow.domains` | `array of string` | none | Domains the session may reach. |
| `block.domains` | `array of string` | none | Domains the session may not reach. |

## Limits and errors

* A policy holds at most 10,000 domains in `allow` and `block` together, 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](https://docs.stophy.dev/browser/overview) opens the session that uses the policy.
* [Network location](https://docs.stophy.dev/browser/network-location.md) chooses the country a session appears in.
* [Policy reference](https://docs.stophy.dev/api-reference/endpoint/browser-network-policy-create.md) lists every field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.