> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skybridge.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# useFiles

> Upload, pick, and resolve files from the host

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](https://docs.skybridge.tech/build/view.md) or a [tool](https://docs.skybridge.tech/build/tools.md) 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.

```tsx highlight={6,12-13,29,33} theme={null}
import { useState } from "react";
import { useFiles } from "skybridge/web";
import { useCallTool } from "../helpers.js"; // generated, type-safe from server schema

function ReceiptAttach() {
  const { upload, getDownloadUrl, selectFiles } = useFiles();
  const { callTool, isPending } = useCallTool("scan-receipt");
  const [error, setError] = useState<string>();

  const attachFromDevice = async (file: File) => {
    try {
      const meta = await upload(file);
      const { downloadUrl } = await getDownloadUrl(meta);
      callTool({
        receipt: {
          file_id: meta.fileId,
          download_url: downloadUrl,
          file_name: meta.fileName,
          mime_type: meta.mimeType,
        },
      });
    } catch (e) {
      setError(String(e));
    }
  };

  const attachFromLibrary = async () => {
    try {
      const [picked] = await selectFiles();
      if (!picked) {
        return;
      }
      const { downloadUrl } = await getDownloadUrl(picked);
      callTool({
        receipt: {
          file_id: picked.fileId,
          download_url: downloadUrl,
          file_name: picked.fileName,
          mime_type: picked.mimeType,
        },
      });
    } catch (e) {
      setError(String(e));
    }
  };

  return (
    <div>
      <input
        type="file"
        disabled={isPending}
        onChange={(e) => {
          const file = e.target.files?.[0];
          if (file) {
            attachFromDevice(file);
          }
        }}
      />
      <button disabled={isPending} onClick={attachFromLibrary}>
        Pick from library
      </button>
      {error && <p>Could not attach receipt: {error}</p>}
    </div>
  );
}
```

Both paths resolve a download URL and build a [`FileRef`](https://docs.skybridge.tech/api-reference/file-ref) 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:

```ts theme={null}
import { NotSupportedError } from "skybridge/web";

try {
  const { downloadUrl } = await getFileDownloadUrl(file);
} catch (e) {
  if (e instanceof NotSupportedError) {
    // fall back to a non-file flow
  }
}
```

## Returns

`useFiles` returns three functions.

### `upload`

```tsx theme={null}
upload(file: File): Promise<FileMetadata>;
```

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

```tsx theme={null}
type FileMetadata = {
  fileId: string;
  fileName?: string;
  mimeType?: string;
};
```

### `getDownloadUrl`

```tsx theme={null}
getDownloadUrl(file: FileMetadata): Promise<{ downloadUrl: string }>;
```

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`

```tsx theme={null}
selectFiles(): Promise<FileMetadata[]>;
```

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.

> [card] [Handle Files](https://docs.skybridge.tech/guides/files.md)
>
> Move files in and out of your app across hosts

> [card] [FileRef](https://docs.skybridge.tech/api-reference/file-ref.md)
>
> The schema that passes a file reference to a tool

> [card] [useCallTool](https://docs.skybridge.tech/api-reference/use-call-tool.md)
>
> Forward an uploaded file into a tool call


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.