Expose the per-file Downloads API (/v1/downloads) in the SDK
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 66/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- openapi, typescript
- Domain
- api, backend-api-design
Research direction
Locate the OpenAPI spec and compare the existing sessions.downloads resource with api.md in the Python and Node SDKs. Add the documented /v1/downloads list, retrieve, and delete operations, and update the session downloads description to identify its zip response. Done means both SDKs expose the generated downloads resource and the session endpoint documents the archive return.
Written by the indexing model from the issue text.
Description
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 withid,sessionId,filename,mimeType,size,checksum(SHA-256, hex) andcreatedAt, plustotal/limit/offsetfor pagination. Optional filters:filename,mimeType,minSize,maxSize,createdAfter,createdBefore,limit(default 20, max 100),offset.
https://docs.browserbase.com/reference/api/list-downloadsGET /v1/downloads/{downloadId}returns the metadata above withAccept: application/json, or the file bytes withAccept: application/octet-stream.
https://docs.browserbase.com/reference/api/get-downloadDELETE /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
mimeTypeand 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/checksumfrom 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
- Add the three
/v1/downloadsendpoints to the OpenAPI spec so they generate into both the Python and Node SDKs as adownloadsresource (list,retrieve,delete). - While there, give
GET /v1/sessions/{id}/downloadsa description that says it returns a zip archive of all files downloaded during the session, sosessions.downloads.list()documents its return type.
- Dominant language
- TypeScript
- Stars
- 64
- Forks
- 17
- Avg merge
- 13m
- Merged PRs (30d)
- 4
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from browserbase/sdk-node
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
browserbase/sdk-node#202 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
browserbase/sdk-node#197 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
browserbase/sdk-node#193 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
browserbase/sdk-node#180 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 68/100
browserbase/sdk-node#214 ·
All issues in browserbase/sdk-node
Similar issues
-
Browser Waiting for: Product Owner
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
getsentry/sentry-javascript#24577 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
agilepathway/label-checker#640 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
copse-dev/agent-pane#2953 ·
-
agentic-workflows
Difficulty 1/5 Under an hour Newbie friendliness 85/100
githubnext/rig#534 ·
-
automation missing-model model-sync provider:pioneer
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
anomalyco/models.dev#7701 ·