File Storage

Upload and download files for your automations

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 provides a cloud bucket for uploading files to use in your automations and downloading files that agents retrieve from websites.

Quick Start

quickstart.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    # Every file belongs to this session.
    session.storage.upload("document.pdf")
    agent = client.Agent(session=session)

    result = agent.run(
        task="Upload document.pdf to the portal and download the receipt", url="https://example.com/upload"
    )

# Download files the agent retrieved
for file in session.storage.list("session_download").files:
    session.storage.download(file.id, local_dir="./downloads")

How It Works

File Storage has two buckets:

Bucket	Purpose	API
Uploads (user_upload)	Files you upload for agents to use	storage.upload()
Downloads (session_download)	Files the browser downloads from websites	storage.list("session_download") + storage.download()

Every session has its own storage, available as session.storage. There is nothing to create or attach first.

┌─────────────┐                    ┌──────────────┐
│ Local Files │ ── upload() ─────> │   Uploads    │
└─────────────┘                    └──────┬───────┘
                                         │
                                         v
                                  ┌──────────────┐
                                  │   Session    │
                                  │   / Agent    │
                                  └──────┬───────┘
                                         │
                                         v
┌─────────────┐                    ┌──────────────┐
│ Local Files │ <── download() ─── │  Downloads   │
└─────────────┘                    └──────────────┘

Uploading Files

Upload files from your local machine to make them available in sessions:

uploading_files.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.storage.upload("report.pdf")
    session.storage.upload("report.pdf", upload_file_name="quarterly_report.pdf")
    print(session.storage.list(source="user_upload").files)

Each file can be up to 1 GiB, with up to 10 GiB stored per session. For larger files, contact the team at [e-mail].

Attaching a URL directly to a form

In a cloud session, pass a public HTTP(S) file URL, including a signed URL, to session.execute(type="upload_file", file_path=...) along with the upload element’s selector or observed ID. Notte downloads and attaches the file without navigating away from the form or requiring a separate session.storage.upload() call.

url_upload.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://test-resources-lovat.vercel.app/upload_fixture.html")
    session.execute(
        type="upload_file",
        selector='input[type="file"]',
        file_path="https://test-resources-lovat.vercel.app/text1.txt",
    )

The download runs on Notte’s servers and does not use browser cookies, browser proxy settings, or custom authentication headers. URLs must resolve to public addresses, including after redirects. Files fetched this way are temporary: they are removed when the session is cleaned up and are not added to the session’s file list.

storage.upload() only accepts local files; URL support belongs to the browser’s upload_file action.

Downloading Files

Download files that agents retrieved from websites:

downloading_files.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Download the invoice from the account page")

# List downloaded files
downloaded = session.storage.list("session_download").files
print(f"Downloaded: {downloaded}")

# Download to local directory
for file in downloaded:
    session.storage.download(file.id, local_dir="./invoices")

Force Overwrite

Overwrite existing local files:

Before running this example, set session_id (Python) or sessionId (Node) to your storage’s session ID, and file_id or fileId to the ID returned by uploading or listing the file. The Node example uses the client initialized above.

force_overwrite.py

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage(session_id)
storage.download(file_id, local_dir="./downloads", force=True)

Using with Agents

Agents can interact with files on websites when storage is attached:

using_with_agents.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.storage.upload("contract.pdf")
    session.storage.upload("signature.png")
    agent = client.Agent(session=session, max_steps=15)

    result = agent.run(
        task="""
        1. Upload contract.pdf to the document portal
        2. Add signature.png to the signature field
        3. Submit the form
        4. Download the signed confirmation
        """,
        url="https://example.com/documents",
    )

# Get the confirmation the agent downloaded
for file in session.storage.list(source="session_download").files:
    session.storage.download(file.id, local_dir="./signed")

Using with Sessions

Use file storage with scripted automation:

using_with_sessions.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.storage.upload("data.csv")
    session.execute(type="goto", url="https://example.com/import")

    # Upload using the upload_file action
    session.execute(type="upload_file", selector='input[type="file"]', file_path="data.csv")

    session.execute(type="click", selector="button.submit")

# Download any files
for file in session.storage.list(source="session_download").files:
    session.storage.download(file.id, local_dir="./results")

API Reference

FileStorage Methods

Method	Description
upload(file_path, upload_file_name=None)	Upload a local file to the session’s storage. Returns a SessionFile
list(source=None, *, limit=100, offset=0)	List files. source is "user_upload", "session_download", or None for both. Returns a page whose .files holds SessionFile objects
download(file_id, local_dir=".", *, force=False)	Save a file to a local directory and return its path
delete(file_id)	Delete a file from storage

Parameters

upload()

• file_path - Path to the local file to upload
• upload_file_name - Optional custom name for the uploaded file

download()

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

Supported File Types

File storage supports all common file types:

• Documents: PDF, DOCX, XLSX, TXT, CSV
• Images: PNG, JPG, JPEG, GIF, WEBP
• Archives: ZIP, RAR, TAR, GZ
• Media: MP4, MP3
• Data: JSON, XML

Best Practices

1. Use Descriptive Filenames

descriptive_filenames.py

from datetime import datetime

from notte_sdk import NotteClient

client = NotteClient()
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
with client.Session() as session:
    session.storage.upload("report.pdf", upload_file_name=f"report_{timestamp}.pdf")

2. Check Downloads After Session

Always check for downloaded files after the session ends:

check_downloads.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Download all invoices")

# Check what was downloaded
files = session.storage.list("session_download").files
if not files:
    print("No files were downloaded")
else:
    for f in files:
        _ = session.storage.download(f.id, local_dir="./invoices")

Next Steps

Sessions

Learn about browser sessions

Vaults

Store credentials securely

Personas

Create browser identities