> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/api-reference/browser-sessions.md).

# Browser Sessions

## GET /sfp/api/browser-sessions

> List browser sessions, optionally filtered

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions":{"get":{"operationId":"BrowserSessionsController_list","summary":"List browser sessions, optionally filtered","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Filter by repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"prNumber","required":false,"in":"query","description":"Filter by pull request number","schema":{"type":"number"}},{"name":"environmentId","required":false,"in":"query","description":"Filter by environment id","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by session status","schema":{"enum":["provisioning","live","ended","expired","error"],"type":"string"}}],"responses":{"200":{"description":"List of browser sessions"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```

## Start a recorded browser session for a PR's assigned review environment

> Resolves the active review-environment assignment for the PR, then dispatches the record flow. Works for pool review-environment sandboxes (which are not named environments). Use POST /environments/:id/browser/record to record against a named environment instead.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RecordForPrDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (owner/repo, or org/project/repo for ADO)"},"prNumber":{"type":"number","description":"Pull request number that has an active review-environment assignment"},"domain":{"type":"string","description":"Review-environment domain (for multi-domain assignments)"},"mode":{"type":"string","description":"Session mode","default":"record"},"retUrl":{"type":"string","description":"Return URL to open in the recorded Salesforce session"}},"required":["repositoryIdentifier","prNumber"]}}},"paths":{"/sfp/api/browser-sessions/record-for-pr":{"post":{"operationId":"BrowserSessionsController_recordForPr","summary":"Start a recorded browser session for a PR's assigned review environment","description":"Resolves the active review-environment assignment for the PR, then dispatches the record flow. Works for pool review-environment sandboxes (which are not named environments). Use POST /environments/:id/browser/record to record against a named environment instead.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordForPrDto"}}}},"responses":{"201":{"description":"Browser session provisioning"},"400":{"description":"No active review environment assigned to the PR"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```

## GET /sfp/api/browser-sessions/{id}

> Get a browser session by id

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}":{"get":{"operationId":"BrowserSessionsController_getById","summary":"Get a browser session by id","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"responses":{"200":{"description":"Browser session details"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Browser session not found"}},"tags":["Browser Sessions"]}}}}
```

## Delete a browser session

> Stops the remote Browserbase session if it is still running, then removes the session record.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}":{"delete":{"operationId":"BrowserSessionsController_remove","summary":"Delete a browser session","description":"Stops the remote Browserbase session if it is still running, then removes the session record.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"responses":{"200":{"description":"Session deleted"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Browser session not found"}},"tags":["Browser Sessions"]}}}}
```

## Update a browser session (internal worker write-back)

> Application-token only. Used by the Hatchet worker to write session faces (provider session id, live view URL, status) back to the server. Not a user-facing endpoint.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UpdateBrowserSessionDto":{"type":"object","properties":{"providerSessionId":{"type":"string","description":"Provider (Browserbase) session id"},"projectId":{"type":"string","description":"Provider project id"},"liveViewUrl":{"type":"string","description":"Live view URL for the running session"},"instanceUrl":{"type":"string","description":"Salesforce instance URL"},"salesforceUsername":{"type":"string","description":"Salesforce username"},"status":{"type":"string","description":"Session status","enum":["provisioning","live","ended","expired","error"]},"error":{"type":"string","description":"Error message if the session failed"},"startedAt":{"type":"string","description":"Session start time (ISO 8601)"},"expiresAt":{"type":"string","description":"Session expiry time (ISO 8601)"}}}}},"paths":{"/sfp/api/browser-sessions/{id}":{"patch":{"operationId":"BrowserSessionsController_update","summary":"Update a browser session (internal worker write-back)","description":"Application-token only. Used by the Hatchet worker to write session faces (provider session id, live view URL, status) back to the server. Not a user-facing endpoint.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrowserSessionDto"}}}},"responses":{"200":{"description":"Updated browser session"},"403":{"description":"Forbidden - Requires role: application"},"404":{"description":"Browser session not found"}},"tags":["Browser Sessions"]}}}}
```

## List replay pages for a recorded session

> Proxies the Browserbase replays listing for the session. Resolved by session id — no environment id required, so it works for pool review environments and the in-app inspect view.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}/replays":{"get":{"operationId":"BrowserSessionsController_listReplays","summary":"List replay pages for a recorded session","description":"Proxies the Browserbase replays listing for the session. Resolved by session id — no environment id required, so it works for pool review environments and the in-app inspect view.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"responses":{"200":{"description":"Replay pages"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"425":{"description":"Replay not available yet (session still running)"}},"tags":["Browser Sessions"]}}}}
```

## Get a replay page playlist (m3u8) for a recorded session

> Proxies the Browserbase replay page and returns its HLS playlist with segment URLs rewritten to the same-origin segment proxy.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}/replays/{pageId}":{"get":{"operationId":"BrowserSessionsController_getReplayPage","summary":"Get a replay page playlist (m3u8) for a recorded session","description":"Proxies the Browserbase replay page and returns its HLS playlist with segment URLs rewritten to the same-origin segment proxy.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}},{"name":"pageId","required":true,"in":"path","description":"Replay page id","schema":{"type":"string"}}],"responses":{"200":{"description":"HLS playlist (application/vnd.apple.mpegurl)"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```

## Stream a recorded replay segment

> Fetches a single HLS segment (or init segment) from the Browserbase CDN server-side and streams it, so the recording stays behind the server auth instead of exposing tokened CDN URLs.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}/replays/{pageId}/segment":{"get":{"operationId":"BrowserSessionsController_getReplaySegment","summary":"Stream a recorded replay segment","description":"Fetches a single HLS segment (or init segment) from the Browserbase CDN server-side and streams it, so the recording stays behind the server auth instead of exposing tokened CDN URLs.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}},{"name":"u","required":true,"in":"query","description":"Opaque (base64url) reference to the CDN segment, as emitted in the proxied playlist","schema":{"type":"string"}},{"name":"pageId","required":true,"in":"path","description":"Replay page id","schema":{}}],"responses":{"200":{"description":"Binary media segment"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```

## Extend a browser session

> Bumps expires\_at by the requested minutes, capped so total lifetime never exceeds 60 minutes.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ExtendBrowserSessionDto":{"type":"object","properties":{"minutes":{"type":"number","description":"Minutes to extend the session by","default":15}}}}},"paths":{"/sfp/api/browser-sessions/{id}/extend":{"post":{"operationId":"BrowserSessionsController_extend","summary":"Extend a browser session","description":"Bumps expires_at by the requested minutes, capped so total lifetime never exceeds 60 minutes.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendBrowserSessionDto"}}}},"responses":{"200":{"description":"Extended browser session"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Browser session not found"}},"tags":["Browser Sessions"]}}}}
```

## Stop a running browser session

> Ends the remote Browserbase session and marks the session ended, keeping the record so its recording can be replayed. Use DELETE to discard the record instead.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/browser-sessions/{id}/stop":{"post":{"operationId":"BrowserSessionsController_stop","summary":"Stop a running browser session","description":"Ends the remote Browserbase session and marks the session ended, keeping the record so its recording can be replayed. Use DELETE to discard the record instead.","parameters":[{"name":"id","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}}],"responses":{"200":{"description":"Session stopped (ended)"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Browser session not found"}},"tags":["Browser Sessions"]}}}}
```

## Start a recorded Browserbase session for an environment

> Provisions a browser session and dispatches the record-browser-session flow to Hatchet. Owner/application only — a recorded session auto-authenticates into the org, matching the owner-gated frontdoor for named environments.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RecordBrowserSessionDto":{"type":"object","properties":{"mode":{"type":"string","description":"Session mode","default":"record"},"retUrl":{"type":"string","description":"Return URL to open in the recorded Salesforce session"},"prNumber":{"type":"number","description":"Pull request number this session is bound to"}}}}},"paths":{"/sfp/api/environments/{envId}/browser/record":{"post":{"operationId":"EnvironmentBrowserController_record","summary":"Start a recorded Browserbase session for an environment","description":"Provisions a browser session and dispatches the record-browser-session flow to Hatchet. Owner/application only — a recorded session auto-authenticates into the org, matching the owner-gated frontdoor for named environments.","parameters":[{"name":"envId","required":true,"in":"path","description":"Environment id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordBrowserSessionDto"}}}},"responses":{"201":{"description":"Browser session provisioning"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment not found"},"409":{"description":"Browserbase integration not configured"}},"tags":["Browser Sessions"]}}}}
```

## List replay pages for a recorded session

> Proxies the Browserbase replays listing for the session.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{envId}/browser/replay/{sessionId}":{"get":{"operationId":"EnvironmentBrowserController_listReplays","summary":"List replay pages for a recorded session","description":"Proxies the Browserbase replays listing for the session.","parameters":[{"name":"sessionId","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}},{"name":"envId","required":true,"in":"path","description":"Environment id","schema":{}}],"responses":{"200":{"description":"Replay pages"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```

## Get a replay page playlist (m3u8) for a recorded session

> Proxies the Browserbase replay page and returns its HLS playlist.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{envId}/browser/replay/{sessionId}/{pageId}":{"get":{"operationId":"EnvironmentBrowserController_getReplayPage","summary":"Get a replay page playlist (m3u8) for a recorded session","description":"Proxies the Browserbase replay page and returns its HLS playlist.","parameters":[{"name":"sessionId","required":true,"in":"path","description":"Browser session id","schema":{"type":"string"}},{"name":"pageId","required":true,"in":"path","description":"Replay page id","schema":{"type":"string"}},{"name":"envId","required":true,"in":"path","description":"Environment id","schema":{}}],"responses":{"200":{"description":"HLS playlist (application/vnd.apple.mpegurl)"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Browser Sessions"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/browser-sessions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.