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

# Browser sessions

> Provision and control browser sessions within a project.

Project sessions manage long-lived browser containers, their cookies, and spawned resources.

## List & create

### GET `/:project/api/sessions`

* **Query** – `limit` & `offset`.
* **Response** – each entry contains `{ id, name, description, image, args, screen, status }` plus metadata obtained from `CloudSessionManager`.

### PUT `/:project/api/sessions`

* **Body**

```json theme={null}
{
  "name": "Chrome bot",
  "description": "Keeps a Chrome window for scraping",
  "screen": { "width": 1440, "height": 900 },
  "args": "",
  "image": "google-chrome",
  "cookies": [],
  "proxy": {
    "protocol": "http",
    "hostname": "proxy.internal",
    "port": 3128,
    "username": "bot",
    "password": "secret"
  }
}
```

* **Behavior** – validates cookies with `assertCookie`, normalizes proxy settings, and persists the session. Returns the new session ID.

## Inspect, update, delete

### GET `/.../sessions/{sessionId}`

Requires read permission for the session. Returns core metadata plus:

* `cookies` when you also have `cookies.read`.
* `resources`: enumerates active resources, each with URLs and status when you have permission to read the underlying session resource.

### PATCH `/.../sessions/{sessionId}`

Accepts any combination of `cookies`, `screen`, `name`, `description`, `args`, `image`, or `proxy`. Fields are validated before calling `CloudSessionManager.update`.

### DELETE `/.../sessions/{sessionId}`

Ensures write permission then removes the session entirely.

## Starting sessions & working with resources

| Endpoint                                             | Description                                                                                    |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `POST /.../sessions/{sessionId}/start`               | Starts a new browser resource. Response contains `{ id, ...info, vncUrl, remoteUrl, status }`. |
| `GET /.../sessions/{sessionId}/{resourceId}`         | Returns metadata and URLs for a specific resource.                                             |
| `GET /.../sessions/{sessionId}/{resourceId}/capture` | Streams captured cookies (requires both resource read and cookies read permissions).           |
| `GET /.../sessions/{sessionId}/{resourceId}/logs`    | Supports SSE or paged JSON logs, filtered by `offset`/`limit`.                                 |
| `POST /.../sessions/{sessionId}/{resourceId}/stop`   | Stops the resource container.                                                                  |

Logs originate from the coordinator and include structured data such as `{ context, severity, message, area, object }`.

Permissions are enforced per resource ID, so sharing a session with another team only grants them access to the exact resources they are authorized to read or execute.