> ## 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 and domain rules

> Choose the country a browser session appears in, use your own proxy or none, and allow or block domains with a saved network policy.

Set the route when you open a session, or change it while the session runs. Tabs and logins stay. Traffic is billed by the network that carried it. See [Pricing](https://docs.stophy.dev/account/pricing.md).

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 300, "location": {"country": "DE"}}'
```

## Options

| Field | Default | Meaning |
| - | - | - |
| `location.country` | none | Two-letter country code. Only on `residential`: sent without `proxy`, it opens the session on `residential`. |
| `proxy` | `direct` | `direct` uses no proxy and has no country. `residential` goes out through a home address in `location.country`, `US` if you send none. A `http`, `https`, `socks5` or `socks5h` URL on a public host uses your own. |

A profile keeps the country it first used. See [Profiles](https://docs.stophy.dev/browser/profiles.md). The closing answer's `exitBytes` splits traffic by network: `managed`, `direct` and `custom`.

## Read and change the route

`GET /v1/browser/{session_id}/proxy` is free and returns `mode`, `country` and `exitIp`, the address sites see. When it cannot be read, `exitIp` is `null` and `exitIpError` says so. Send the request again.

| `mode` | Meaning | `country` | `exitIp` |
| - | - | - | - |
| `managed` | Residential, in a country you pick | Lower case code | Address sites see |
| `direct` | No proxy | `null` | Address sites see |
| `custom` | Your own proxy | `null` | `null` |

`PATCH` the same path to change a running session. Open connections end and new ones use the new route. Send one body:

| Body | You get |
| - | - |
| `{"mode": "managed", "country": "JP"}` | A visitor from that country |
| `{"rotate": true}` | A new address in the same country |
| `{"mode": "direct"}` | No proxy |
| `{"mode": "custom", "customProxy": {"host": "proxy.example.net", "port": 8080}}` | Your own proxy. `host` and `port` are required. `username`, `password` and `protocol` are optional. |

A body with nothing to change answers as `GET` does.

## Network policies

A policy is a saved list of domains that several sessions share. Policies are free. A domain such as `example.com` covers itself and every subdomain, and the most specific entry wins. Domains are trimmed, lower-cased and de-duplicated, and a leading `*.` is dropped.

```bash 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"]}}'
```

This allowlist blocks everything except those two sites. To block a few sites instead, leave `defaultAction` out, which means `allow`, and list them in `block.domains`. The answer has `id` and `version`.

| Field | Default | Meaning |
| - | - | - |
| `name` | none | 1 to 100 characters. Required to create. |
| `defaultAction` | `allow` | `allow` or `block`, for a domain no entry matches |
| `allow.domains`, `block.domains` | none | Domains the session may or may not reach |

Open a session with `"networkPolicyId": "<id>"`. It returns `networkPolicyVersion`, the version it enforces. The policy checks every request, not only the page address. For a short list that belongs to one session, send `"allowedDomains": ["example.com"]` instead, up to 100 domains, and not with `networkPolicyId`.

| Action | Call |
| - | - |
| Create | `POST /v1/browser/network-policies` |
| 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}` |
| Change | `PATCH /v1/browser/network-policies/{policy_id}`. Each field you send replaces the old one, a list replaces the whole list, and `version` goes up by 1. |
| Delete | `DELETE /v1/browser/network-policies/{policy_id}`, only when no running session uses it |

A change reaches running sessions within seconds. The answer has `runningSessions`, `appliedSessions`, and `pendingSessionIds` for sessions not reached yet, which keep the old policy until their `networkPolicyVersion` catches up. A change that blocks a host closes its open connections, counted in `closedConnections`.

A policy holds at most 10,000 domains in `allow` and `block` together. An account holds at most 100 policies.

## Errors

All return `400 invalidRequest` unless noted.

* `location.country` with `proxy` set to `direct` or a URL. A country needs `residential`.
* A country that is not two letters, a `proxy` that is not `residential`, `direct` or a public URL, or a `customProxy.host` that is not public, such as `localhost`.
* A URL, path, port, IP address, other wildcard, or a domain in both lists in a policy.
* `allowedDomains` with `networkPolicyId`.
* A session that is not running: `409 invalidRequest`.
* Deleting a policy a running session uses: `409 invalidRequest`. Close the session first.
* An unknown policy: `404 notFound`.


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