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

# Project proxies

> Store per-project proxy credentials or fetch dynamic proxies from providers.

Proxy records help you route browser sessions or MCP calls through customer-managed networks.

## List proxies

### GET `/:project/api/proxies`

* **Query** – `source=db` forces the API to return only proxies stored in the database. Without the query parameter, Browsary asks the configured `ProxyProvider` for dynamic proxies tied to the user and project.
* **Response** – array of proxy descriptors `{ id?, name?, hostname, port, protocol, username?, password?, metadata }`.

## Create

### POST `/:project/api/proxies`

* **Auth** – requires `proxies.write` on the project.
* **Body**

```json theme={null}
{
  "name": "Corp exit node",
  "hostname": "proxy.corp.example",
  "port": 3128,
  "protocol": "http",
  "username": "bot",
  "password": "secret",
  "metadata": { "region": "us-east-1" }
}
```

* **Validation** – hostname/protocol must be non-empty strings; port must be a positive integer. Optional fields are checked for type consistency.
* **Response** – the created proxy row as stored in the database.

## Get / patch / delete

| Endpoint                        | Description                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `GET /.../proxies/{proxyId}`    | Requires read permission for the specific proxy. Returns the stored record or HTTP 404 if not found.                      |
| `PATCH /.../proxies/{proxyId}`  | Accepts any field from the create payload. Empty usernames/passwords are normalized to `null`. Metadata defaults to `{}`. |
| `DELETE /.../proxies/{proxyId}` | Removes the record permanently.                                                                                           |

Combine these endpoints with session creation (`PUT /:project/api/sessions`) to enforce proxy usage for specific browser runs.