File Storage

AI agent instructions

STOP. Do not read past this section until you have read and followed /quickstart.md.Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live observe() call, CLI notte page observe output, or generated workflow code. Guessed browser targets fail on real pages.Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with notte sessions workflow-code before using SDK docs or SDK code.SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.

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:

Bucket	Purpose	API
Uploads	Files you upload for agents to use	`storage.upload()`
Downloads	Files agents download from websites	`storage.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}")

Each uploaded file must be under 100 MB. For larger files, contact the team at support@notte.cc.

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

Method	Description
`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

Getting Started

Sessions

Agents

Functions

Agent Tools

Scraping

Guides

Integrations

File Storage

Quick Start

How It Works

Uploading Files

Downloading Files

Force Overwrite

Using with Agents

Using with Sessions

API Reference

FileStorage Methods

Parameters

Supported File Types

Best Practices

1. Attach Storage Before Starting

2. Use Descriptive Filenames

3. Check Downloads After Session

Next Steps

Agents

Sessions

Vaults

Personas

​Quick Start

​How It Works

​Uploading Files

​Downloading Files

​Force Overwrite

​Using with Agents

​Using with Sessions

​API Reference

​FileStorage Methods

​Parameters

​Supported File Types

​Best Practices

​1. Attach Storage Before Starting

​2. Use Descriptive Filenames

​3. Check Downloads After Session

​Next Steps

Agents

Sessions

Vaults

Personas

Quick Start

How It Works

Uploading Files

Downloading Files

Force Overwrite

Using with Agents

Using with Sessions

API Reference

FileStorage Methods

Parameters

Supported File Types

Best Practices

1. Attach Storage Before Starting

2. Use Descriptive Filenames

3. Check Downloads After Session

Next Steps