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

[jayozer]

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.

[jayozer]

Same request against the Python SDK, which has the identical gap: browserbase/sdk-python#192.

[jayozer]

Some context on where the gap is, in case it helps triage: the endpoints are already in the OpenAPI spec both SDKs are generated from, but they are not configured in the Stainless project.

Both SDKs come from the same Stainless project, and through v1.15.0 the Python repo's .stats.yml recorded the spec snapshot each release was generated from, so this is checkable from browserbase/sdk-python's git history:

• v1.7.0 (2026-03-16, .stats.yml at 36f6772): 16 paths in the spec, no /v1/downloads.
• v1.9.0 (2026-05-13, dfaea80): /v1/downloads and /v1/downloads/{id} are in the spec with Downloads_list, Downloads_get and Downloads_delete (snapshot). 23 endpoints configured; none of the three.
• v1.15.0 (2026-07-14, 919bb95): the same three operations are still in the spec (snapshot). 38 endpoints configured; still none of the three. This repo's .stats.yml shows the same 38.

Since then the SDKs picked up 15 endpoints from that same spec (agents, fetch, search, certificates, recording downloads, ...) while these stayed excluded. /v1/functions is in the same position, so this may be deliberate gating. If it is, it would help to know whether the per-file Downloads API is GA and whether the zip endpoint is the supported path in the meantime.

Two related data points: the downloads docs show raw requests / fetch calls rather than SDK methods, and the Box integration in browserbase/integrations (examples/integrations/box/agent/src/downloads.ts) also calls /v1/downloads with fetch alongside the SDK.

If the API is GA, exposing it looks like a configuration change rather than new spec work.