SOP 010: Files API

Fresh

Field	Value
SOP ID	SOP-010
Version	1.0
Status	Active
Source	Steel Files API

Overview

Steel provides two file management systems: Session Files for working with files within active browser sessions, and Global Files for persistent storage across your organization.

File System Architecture

Session Files API

Upload Files to Session

const file = fs.createReadStream("./data.csv");
const session = await client.sessions.create();
const uploadedFile = await client.sessions.files.upload(session.id, {
  file: file,
});

List Session Files

const files = await client.sessions.files.list(sessionId);
files.forEach(file => {
  console.log(`${file.path} | Size: ${file.size}`);
});

Download Session Files

// Download specific file
const response = await client.sessions.files.download(sessionId, "path/to/file");
const fileBlob = await response.blob();

// Download all as zip archive
const archive = await client.sessions.files.downloadArchive(sessionId);

Delete Session Files

// Delete specific file
await client.sessions.files.delete(sessionId, "path/to/file");

// Delete all files
await client.sessions.files.deleteAll(session.id);

Global Files API

Upload to Global Storage

const file = fs.createReadStream("./dataset.csv");
const globalFile = await client.files.upload({ file });
console.log(globalFile.path); // dataset.csv

Use Global File in Session

const session = await client.sessions.create();
const sessionFile = await client.sessions.files.upload(session.id, {
  file: globalFile.path  // Reference global file
});

List, Download, Delete

// List all global files
const files = await client.files.list();

// Download
const response = await client.files.download(file.path);

// Delete
await client.files.delete(file.path);

Using Files in Browser Automation

Set File Input via CDP

const cdpSession = await currentContext.newCDPSession(page);
const document = await cdpSession.send("DOM.getDocument");
const inputNode = await cdpSession.send("DOM.querySelector", {
  nodeId: document.root.nodeId,
  selector: "#file-input"
});

await cdpSession.send("DOM.setFileInputFiles", {
  files: [uploadedSessionFile.path],
  nodeId: inputNode.nodeId,
});

Standard Playwright Upload

await page.setInputFiles("#file-input", [uploadedSessionFile.path]);

Key Behaviors

• Session files are accessible from the browser within the VM
• Files persist beyond session lifecycle (auto-backed up)
• Session files are automatically promoted to global storage on release
• Global files can be mounted in any session

Verification Checklist

• [ ] File uploaded to session successfully
• [ ] File accessible within browser automation
• [ ] File input elements can reference uploaded files
• [ ] Downloaded files match originals
• [ ] Files appear in global storage after session release

Troubleshooting

Issue	Solution
Upload fails	Check file size, verify session is live
File not found in browser	Verify upload path, ensure session is active
CDP file input fails	Check selector matches, verify node exists
Global file not mounting	Verify global file path is correct

See Also

• SOP 001: Create & Manage Sessions
• Cookbook: Files Starter