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

# FileRef

> Reference a host-managed file in a tool's schema

`FileRef` is a reference to a file, an id and a URL to fetch its bytes. Use it in a [tool's `inputSchema` or `outputSchema`](https://docs.skybridge.tech/api-reference/register-tool#inputschema-outputschema) to pass files in and out.

> [!NOTE]
>
> File params are a **ChatGPT** feature. Other hosts don't pass files through [tool](https://docs.skybridge.tech/build/tools.md) calls, so a `FileRef` field is populated only on ChatGPT.

## Example

`summarize-document` takes a file in, fetches its bytes from `download_url`, and returns a summary file back.

```ts server.ts highlight={10-11} theme={null}
import { FileRef, Skybridge } from "skybridge/server";

export const app = new Skybridge({
  name: "docs",
  version: "1.0",
  handler: (server) =>
    server.registerTool(
      {
        name: "summarize-document",
        inputSchema: { document: FileRef },
        outputSchema: { summary: FileRef },
        _meta: { "openai/fileParams": ["document"] },
      },
      async ({ document }) => {
        const bytes = await fetch(document.download_url).then((r) => r.blob());
        const summary = await summarize(bytes); // returns a FileRef
        return { structuredContent: { summary } };
      },
    ),
});
```

## Shape

```ts theme={null}
type FileRef = {
  file_id: string;
  download_url: string;
  mime_type?: string;
  file_name?: string;
};
```

| Field | Purpose |
| - | - |
| `file_id` | The host's identifier for the file. |
| `download_url` | A URL to fetch the file's bytes. |
| `mime_type` | The file's MIME type, when known. |
| `file_name` | The original file name, when known. |

`download_url` is required in both positions: on input the host fills it, on output your handler produces a URL the host can fetch.

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

> [card] [useFiles](https://docs.skybridge.tech/api-reference/use-files.md)
>
> Upload, pick, and resolve files from the view

> [card] [registerTool](https://docs.skybridge.tech/api-reference/register-tool.md)
>
> Declare file params with `openai/fileParams`


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