File Storage

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 manages session-owned uploads and browser downloads. Upload files for your automation to attach to forms, and retrieve files the browser saves.

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")

    session.execute(type="goto", url="https://example.com/upload")
    session.execute(type="upload_file", selector='input[type="file"]', file_path="document.pdf")
    session.execute(type="download_file", selector="a.receipt")

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

How It Works

Files have two sources:

Source	Purpose	API
Uploads	Files you upload for sessions to use	`storage.upload()`
Downloads	Files sessions download from websites	`storage.download()`

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

Uploading Files

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

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)

const client = new NotteClient();
const storage = client.FileStorage();
await client.Session({ storage }).use(async session => {
  await storage.upload('report.pdf');
  await storage.upload('report.pdf', 'quarterly_report.pdf');
  console.log((await 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 support@notte.cc.

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.

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",
    )

const { NotteClient } = await import('notte-sdk');

const client = new NotteClient();

await client.Session().use(async session => {
  await session.execute({
    type: 'goto', url: 'https://test-resources-lovat.vercel.app/upload_fixture.html',
  });
  await 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 your session retrieved from websites with the download_file action:

downloading_files.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://example.com/account")
    session.execute(type="download_file", selector="a.invoice")

# 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.

from notte_sdk import NotteClient

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

const storage = client.FileStorage(sessionId);
await storage.download(fileId, './downloads', { force: true });

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 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 sessions

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

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")

const { NotteClient } = await import('notte-sdk');

const client = new NotteClient();
const now = new Date();
const date = [now.getFullYear(), now.getMonth() + 1, now.getDate()].map(n => String(n).padStart(2, '0')).join('');
const time = [now.getHours(), now.getMinutes(), now.getSeconds()].map(n => String(n).padStart(2, '0')).join('');
const timestamp = `${date}_${time}`;
const storage = client.FileStorage();
await client.Session({ storage }).use(async session => {
  await storage.upload('report.pdf', `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:
    session.execute(type="goto", url="https://example.com/account")
    session.execute(type="download_file", selector="a.invoice")

# 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

Getting Started

Sessions

Authentication

Functions

Web API

Guides

File Storage

Quick Start

How It Works

Uploading Files

Attaching a URL directly to a form

Downloading Files

Force Overwrite

Using with Sessions

API Reference

FileStorage Methods

Parameters

Supported File Types

Best Practices

1. Use Descriptive Filenames

2. Check Downloads After Session

Next Steps

Sessions

Vaults

Personas

​Quick Start

​How It Works

​Uploading Files

​Attaching a URL directly to a form

​Downloading Files

​Force Overwrite

​Using with Sessions

​API Reference

​FileStorage Methods

​Parameters

​Supported File Types

​Best Practices

​1. Use Descriptive Filenames

​2. Check Downloads After Session

​Next Steps

Sessions

Vaults

Personas

Quick Start

How It Works

Uploading Files

Attaching a URL directly to a form

Downloading Files

Force Overwrite

Using with Sessions

API Reference

FileStorage Methods

Parameters

Supported File Types

Best Practices

1. Use Descriptive Filenames

2. Check Downloads After Session

Next Steps