Expose the per-file Downloads API (/v1/downloads) in the SDK #192

What exists today

The only way to retrieve downloaded files through the SDK is client.sessions.downloads.list(id). It calls GET /v1/sessions/{id}/downloads with Accept: application/zip and hands back the raw response (BinaryAPIResponse in Python, Response in Node): a zip archive containing every file the session downloaded. Nothing in the method's description says so. The generated docstring is just "Session Downloads", so the first hint that you are holding a zip is the response body.

What's missing

Browserbase documents a per-file Downloads API that is not in the SDK at all. Neither SDK has a downloads resource, and api.md in each lists only the zip endpoint and sessions.recording.downloads. The documented endpoints:

• GET /v1/downloads?sessionId=<id> lists individual downloads with id, sessionId, filename, mimeType, size, checksum (SHA-256, hex) and createdAt, plus total / limit / offset for pagination. Optional filters: filename, mimeType, minSize, maxSize, createdAfter, createdBefore, limit (default 20, max 100), offset.
  https://docs.browserbase.com/reference/api/list-downloads
• GET /v1/downloads/{downloadId} returns the metadata above with Accept: application/json, or the file bytes with Accept: application/octet-stream.
  https://docs.browserbase.com/reference/api/get-download
• DELETE /v1/downloads/{downloadId} deletes one download and returns 204.
  https://docs.browserbase.com/reference/api/delete-download

Feature overview: https://docs.browserbase.com/features/downloads

Why it matters

• Per-file access with mimeType and size filters and pagination, instead of one opaque archive per session.
• No zip round-trip when you want a single file: fetch it by id and you are done.
• A caller can gate on one body's magic bytes, or compare size / checksum from the listing, before doing anything with the file.

Our integration ended up dropping the SDK for these calls and using raw httpx against /v1/downloads for exactly these reasons. The client's get() plus make_request_options() covers the gap in the meantime, but it means hand-writing the types the generator would otherwise produce.

Ask

1. Add the three /v1/downloads endpoints to the OpenAPI spec so they generate into both the Python and Node SDKs as a downloads resource (list, retrieve, delete).
2. While there, give GET /v1/sessions/{id}/downloads a description that says it returns a zip archive of all files downloaded during the session, so sessions.downloads.list() documents its return type.