FileStorage

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

File storage lets you upload files for the browser to attach to forms, and retrieve files the browser downloads. Storage is scoped to a session: every file operation needs a session ID, and each session exposes its storage as session.storage. Files expire after a retention period, so download the ones you need.

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Upload a local file so the browser can attach it to a form
    session.storage.upload("document.pdf")

    agent = client.Agent(session=session)
    agent.run(task="Upload document.pdf and download the receipt")

    # Download the files the browser saved during the session
    for file in session.storage.list(source="session_download").files:
        session.storage.download(file.id, local_dir="./downloads")

To work with the files of an existing session, bind storage to its ID with client.FileStorage(session_id="<session-id>").

Methods

upload

upload(file_path: str, upload_file_name: str | None = None) -> SessionFile

Upload a local file to the session. Parameters:

file_path - Path to the local file
upload_file_name - Optional custom name for the file in storage

Returns: SessionFile - The stored file (id, filename, mime_type, size, checksum, source, created_at, expires_at)

list

list(source: FileSource | str | None = None, *, limit: int = 100, offset: int = 0) -> SessionFilesPage

List the session’s files that have not expired. Parameters:

source - "user_upload" for files you uploaded, "session_download" for files the browser downloaded, or None for both
limit - Maximum number of files to return (default: 100)
offset - Number of files to skip, for pagination (default: 0)

Returns: SessionFilesPage - files (a list of SessionFile), total, limit and offset

download

download(file_id: str, local_dir: str = ".", *, force: bool = False) -> str

Download a file to a local directory, keeping its stored filename. Parameters:

file_id - ID of the file, from upload() or list()
local_dir - Local directory to save the file (default: current directory)
force - Overwrite an existing local file (default: False). Without it, an existing file raises FileExistsError.

Returns: str - Path of the downloaded file

delete

delete(file_id: str) -> None

Delete a file from the session’s storage. Parameters:

file_id - ID of the file to delete

File metadata

To get a single file’s metadata without downloading it, use client.files.metadata(session_id, file_id), which returns its SessionFile.

Parameters

UnionType[str, None]

default:"None"

Getting Started

APIs

Python SDK

Node SDK

Methods

upload

list

download

delete

File metadata

Parameters

​Methods

​upload

​list

​download

​delete

​File metadata

​Parameters

Methods

upload

list

download

delete

File metadata

Parameters