Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notte.cc/llms.txt

Use this file to discover all available pages before exploring further.

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()
storage = client.FileStorage()

# Upload a file before the session
storage.upload("document.pdf")

# Create session with storage attached
with client.Session(storage=storage) as session:
    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 storage.list_downloaded_files():
    storage.download(file_name=file.name, local_dir="./downloads")

​
How It Works

File Storage has two buckets:
BucketPurposeAPI
UploadsFiles you upload for agents to usestorage.upload()
DownloadsFiles agents download from websitesstorage.download()
┌─────────────┐                    ┌──────────────┐
│ 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()
storage = client.FileStorage()

# Upload a file (uses the original filename)
storage.upload("report.pdf")

# Upload with a custom name
storage.upload("report.pdf", upload_file_name="quarterly_report.pdf")

# List uploaded files
files = storage.list_uploaded_files()
print(f"Uploaded: {files}")

​
Downloading Files

Download files that agents retrieved from websites:
downloading_files.py
from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

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

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

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

​
Force Overwrite

Overwrite existing local files:
force_overwrite.py
from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

storage.download(
    file_name="report.pdf",
    local_dir="./downloads",
    force=True,  # Overwrite if exists
)

​
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()
storage = client.FileStorage()

# Upload files for the agent to use
storage.upload("contract.pdf")
storage.upload("signature.png")

with client.Session(storage=storage) as session:
    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 storage.list_downloaded_files():
    storage.download(file_name=file.name, local_dir="./signed")

​
Using with Sessions

Use file storage with scripted automation:
using_with_sessions.py
from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

# Upload file
storage.upload("data.csv")

with client.Session(storage=storage) as session:
    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 storage.list_downloaded_files():
    storage.download(file_name=file.name, local_dir="./results")

​
API Reference

​
FileStorage Methods

MethodDescription
upload(file_path, upload_file_name=None)Upload a local file to storage
download(file_name, local_dir, force=False)Download a file to local directory
list_uploaded_files()List files you’ve uploaded
list_downloaded_files()List files downloaded by agents

​
Parameters

upload()
  • file_path - Path to the local file to upload
  • upload_file_name - Optional custom name for the uploaded file
download()
  • file_name - Name of the file in storage
  • local_dir - Local directory to save the file
  • force - Overwrite existing 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. Attach Storage Before Starting

Always create and attach storage before starting the session:
attach_before_starting.py
from notte_sdk import NotteClient

client = NotteClient()

# Correct
storage = client.FileStorage()
storage.upload("file.pdf")

with client.Session(storage=storage) as session:
    # Storage is available
    pass

​
2. Use Descriptive Filenames

descriptive_filenames.py
from datetime import datetime

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
storage.upload("report.pdf", upload_file_name=f"report_{timestamp}.pdf")

​
3. Check Downloads After Session

Always check for downloaded files after the session ends:
check_downloads.py
from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

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

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

​
Next Steps

Agents

Use agents with file operations

Sessions

Learn about browser sessions

Vaults

Store credentials securely

Personas

Create browser identities