Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
#192 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
70/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
node.js, openapi, python

Research direction

Start by locating the OpenAPI spec and the generated API documentation, including api.md in the SDKs. Add the three documented /v1/downloads operations and update the session downloads description, then verify generation produces downloads.list, downloads.retrieve, and downloads.delete for the Python and Node SDKs.

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:

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.
Dominant language
Python
Stars
93
Forks
16
Avg merge
11m
Merged PRs (30d)
3

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from browserbase/sdk-python

All issues in browserbase/sdk-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.