Trigger a file download inside a Browserbase session and retrieve the file through the Downloads API

Documented steps

1. Create a session (POST https://api.browserbase.com/v1/sessions, header X-BB-API-Key) and connect Playwright or Puppeteer to its connectUrl.
2. Before triggering any download, open a CDP session on the page and call Browser.setDownloadBehavior with { behavior: "allow", downloadPath: "downloads", eventsEnabled: true }. Reference: https://docs.browserbase.com/platform/browser/files/downloads
3. Use the literal string "downloads" as downloadPath - not an absolute path. Without this configuration the file will not be available for retrieval.
4. Trigger the download in the page (click the link or button). Files sync to Browserbase cloud storage in real time once the CDP behavior is set.
5. Poll GET https://api.browserbase.com/v1/downloads?sessionId={sessionId} with header X-BB-API-Key. sessionId is a required query parameter.
6. Retry the poll on an interval - the documented example polls every 2 seconds for up to 20 seconds, because large downloads may not be immediately available.
7. Narrow results with optional query parameters filename, mimeType, minSize, maxSize, createdAfter, createdBefore, limit (default 20, max 100) and offset. Reference: https://docs.browserbase.com/reference/api/list-downloads
8. Read the response shape: { downloads: [{ id, sessionId, filename, mimeType, size, checksum, createdAt }], total, limit, offset }.
9. Fetch the bytes with GET https://api.browserbase.com/v1/downloads/{id} using header Accept: application/octet-stream. Use Accept: application/json on the same URL to get metadata only.
10. Verify integrity against the checksum field before trusting the file, then optionally DELETE https://api.browserbase.com/v1/downloads/{id} (returns 204 No Content) to remove it from storage.