Skip to main content
ChatGPT stores your app’s files and hands your code a reference to each, never the bytes. useFiles produces a reference from a file the user supplies, by uploading a local file or picking one from ChatGPT’s library, and resolves any reference into a download URL the view or a tool can fetch.

Example

A shopper attaches a receipt, from their device or their ChatGPT library, and the view hands it to a tool that scans it.
Both paths resolve a download URL and build a FileRef by hand: the hook returns camelCase fields, while FileRef wants snake_case with a required download_url.

Host support

The file APIs depend on the host exposing them on window.openai. Host versions differ: ChatGPT web has uploadFile, selectFiles and getFileDownloadUrl, while the current desktop build has none of them. When a method is missing, calling it throws NotSupportedError, so feature-detect with instanceof when the view runs cross-host:

Returns

useFiles returns three functions.

upload

Sends a File to the host and resolves with its FileMetadata, a reference to the stored file (the host never gives the view the bytes, only this handle):

getDownloadUrl

Resolves a download URL for a host-managed file: one returned by upload or selectFiles, or one delivered to the view through a tool’s output.

selectFiles

Opens ChatGPT’s file library picker and resolves with the FileMetadata of the files the user authorizes for the app. The array is empty when the user picks nothing.

Handle Files

Move files in and out of your app across hosts

FileRef

The schema that passes a file reference to a tool

useCallTool

Forward an uploaded file into a tool call