> ## 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.

# External sessions

> Bootstrap temporary browser containers from trusted infrastructure using a shared external token.

All endpoints in this section require the `external` middleware. Provide the shared secret via the `Authorization` header (`Bearer <EXTERNAL_TOKEN>` or `Token <EXTERNAL_TOKEN>`) or a `?token=` query parameter.

## POST `/api/external-session`

Creates a disposable browser container that you control outside of the project-scoped session manager.

* **Body**

```json theme={null}
{
  "screen": { "width": 1280, "height": 720 },
  "args": "--disable-gpu",
  "image": "google-chrome",
  "proxy": {
    "protocol": "http",
    "hostname": "proxy.internal",
    "port": 3128,
    "username": "bot",
    "password": "secret"
  }
}
```

`proxy` is optional. When present it is validated with `parseProxySettings`.

* **Response**

```json theme={null}
{
  "id": "tmp_123",
  "password": "container-vnc-password",
  "vncUrl": "wss://.../vnc",
  "remoteUrl": "https://.../remote"
}
```

Use the URLs to connect to the headless browser’s VNC or remote debugging interfaces.

## GET `/api/external-session/{id}/capture`

Streams cookies captured during the session back to the caller.

* **Auth** – same token requirement as the create call.
* **Response** – array of cookie records identical to the ones stored in project sessions.

This endpoint leverages `TemporarySessionResource.capture()` under the hood, so it only returns data while the resource exists.