Wiki · Concept · Last reviewed June 25, 2026

File Handling API

The File Handling API lets an installed web app register as a handler for selected file types and receive opened files through launch parameters.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, progressive web apps, file handling, installed web apps, agents, local data

Definition

The File Handling API is a web platform feature for installed progressive web apps. It lets a web app declare, in its Web App Manifest, that it can handle particular file types. MDN describes the file_handlers manifest member as an array of objects representing the file types an installed PWA can handle, and says the browser reads it at installation time to associate the app with those file types at the operating-system level.

This is different from the File System Access API. File System Access starts with a web app asking the user to pick a file or directory. File Handling starts outside the web app: a user double-clicks, opens with, or otherwise routes a local file through the operating system, and the installed web app is launched as one possible handler.

How It Works

The WICG Manifest Incubations draft defines file_handlers as a list that provides instructions for file-opening actions originating outside the app itself. Each handler represents an in-scope URL that can handle launches for accepted file types. The key fields are action, accept, optional name, optional icons, and launch_type. The accept dictionary maps MIME types to file extensions, and the draft says both MIME type and extension are needed because operating systems differ in how they register file associations.

When a file handler launch happens, the app receives file data through LaunchParams.files, using the same launch queue family as the Launch Handler API. MDN notes that the handling code runs in the application JavaScript on the main thread, not in the service worker. Chrome documentation adds that launch_type can express whether multiple files should arrive in one client or in multiple clients, subject to platform limits.

Agent Context

For AI Browsers and Computer Use, file handling is a local-data boundary. A browser agent in a text editor, spreadsheet tool, design app, coding workspace, legal review tool, or claims workflow may receive a file because the user opened it from the desktop, downloads folder, file manager, or another app. The agent may then summarize, transform, upload, classify, rewrite, or act on that file.

The important governance question is whether the user meant to hand the file to the agent, not merely to the app shell. A file-open action can feel ordinary and local while still giving a networked web application access to sensitive content. The record should preserve the distinction between opening the file, reading the file, sending derived content to a model, and writing changes back.

Governance Use

A governed deployment should review every declared file type. The handler should match the app's real purpose, avoid overbroad wildcard accept lists, use clear names and icons where supported, and route each action URL to an auditable file-import path. If the app can become the default handler for a file type, policy should say how that default is disclosed, revoked, and tested after updates.

For agent-facing apps, pair file handling with data-loss prevention, file provenance, model input logging, and writeback controls. The safe pattern is narrow: accept only necessary extensions, inspect size and type before processing, require user confirmation before model upload or destructive rewrite, and keep a local audit record that does not copy full document contents by default.

Limits

MDN marks file_handlers as experimental and not Baseline because it is not supported in some widely used browsers. Chrome documentation says file handling is limited to desktop operating systems. The WICG draft also leaves management, presentation, and selection of registered handlers to the operating system, so user experience varies.

File handling is not proof of safe parsing, content validation, malware scanning, or user consent for every downstream use. It opens a file-handling path; it does not decide what the app or agent may ethically do with the file.

Minimum Evidence Record

For an agent-facing installed web app, record the manifest URL, app id if present, origin, handler action, accepted MIME types and extensions, launch_type, file names or hashes where appropriate, file sizes, OS launch surface if available, user confirmation, model-upload decision, writeback decision, agent task identifier, and any rejected file or cancelled action.

Source Discipline

Use WICG Manifest Incubations for the normative shape of file_handlers, handler processing, launch type, and privacy considerations. Use MDN for developer-facing compatibility warnings and implementation summaries. Use Chrome and Microsoft Edge documentation for browser-specific workflow notes and examples.

Spiralist Reading

Spiralism reads file handling as a quiet door between the desktop and the web. The user thinks in files: a brief, a spreadsheet, an image, a sketch, a transcript. The web app thinks in launch parameters and handles. The humane design makes that conversion visible before an agent turns a local object into remote cognition.

Sources

Return to Wiki