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()
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	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:

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 uploaded file must be under 100 MB. 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 the API server and does not use browser cookies, browser proxy settings, or custom authentication headers. URLs must resolve to public addresses; redirects are checked too. Downloads have a 120-second overall limit, up to five redirects, and the server’s configured per-file and aggregate temporary-upload size limits. Temporary files are removed when the session is cleaned up and are not added to its persistent file catalog. This requires cloud backend support, with no SDK update. Standalone local sessions retain their existing storage/path behavior. storage.upload() still 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.

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

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Storage is always available and scoped to the session.
    session.storage.upload("file.pdf")

const client = new NotteClient();
const storage = client.FileStorage();
await client.Session({ storage }).use(async session => {
  // Storage is always available and scoped to the session.
  await storage.upload('file.pdf');
});

2. 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`);
});

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

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

Sessions

Vaults

Personas

​Quick Start

​How It Works

​Uploading Files

​Attaching a URL directly to a form

​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

Sessions

Vaults

Personas

Quick Start

How It Works

Uploading Files

Attaching a URL directly to a form

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