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

# Send a file to a run

> Give a tool's file field an uploaded file, an https URL or a data URI.

This page shows how to give a tool a file. A tool's file field is a string that takes one of three values:

* **A file ID** (`file_...`) from an upload. Use this for any file larger than a few hundred kilobytes.
* **An https URL.** Pomerado fetches it when you submit the run.
* **A `data:` URI** of at most 512 KB, such as `data:application/pdf;base64,JVBERi0...`.

## Upload a file

<Steps>
  <Step title="Create the upload">
    Send `POST /v1/files` with the file's name and media type. In an MCP client, call `create_file_upload`, on the Pomerado MCP and every integration MCP; its answer adds the `curl -T` command for the `upload_url`.

    ```json theme={null}
    { "name": "receipt.pdf", "media_type": "application/pdf", "size": 48213 }
    ```

    `size` is optional; when you give it, the upload must be exactly that long. The answer has the file's `id` and a one-time `upload_url`.
  </Step>

  <Step title="Send the bytes">
    PUT the file to `upload_url` once, with no `Authorization` header:

    ```bash theme={null}
    curl -T receipt.pdf -H "Content-Type: application/pdf" "$UPLOAD_URL"
    ```

    The answer is the file, now `ready`. If the upload fails, send it again before the file expires.
  </Step>

  <Step title="Pass the ID to the run">
    Use the file's ID as the field's value when you [run the tool](/guides/tools/run-tools):

    ```json theme={null}
    { "input": { "receipt": "file_3b9e0c6f1a2d4e5f8a7b6c5d4e3f2a1b" } }
    ```
  </Step>
</Steps>

A file serves one run. `GET /v1/files/{id}` reads its metadata, never its bytes, and `DELETE /v1/files/{id}` erases it now.

## On MCP

A tool's file fields sit at the top level of its parameters, next to `input`, and are listed in `_meta["openai/fileParams"]`, so ChatGPT can attach a file the user gave it; Pomerado fetches the attached file's `download_url` as it fetches any https URL. A file field named like one of the call's own parameters is called `file_<name>` there. Each still takes a file ID, an https URL or a `data:` URI, and a list of files keeps its own limits, such as `maxItems`.

## Give a build an example file

A [build](/guides/build/overview) runs one real example. When the example needs a file, upload it first and put its file ID anywhere in `example_input`:

```json theme={null}
{ "example_input": { "receipt": "file_3b9e0c6f1a2d4e5f8a7b6c5d4e3f2a1b" } }
```

The build takes the file as a run does and erases it when the build ends. Only file IDs count as files here, not URLs or `data:` URIs. The model that builds the tool never sees the file's bytes or its ID, only its name, type and size. A file the example downloads gives the build only its name, type, size and hash, and is kept nowhere. A build answers the same `file_unavailable` and `file_limit_exceeded` errors as a run.

<Accordion title="Details">
  * A URL must be https on the default port, with no username or password, and resolve to a public address. It may redirect at most three times, must answer within 20 seconds and must send a `Content-Length`.
  * Pomerado stores a URL's or data URI's bytes like an upload.
  * See [limits](/guides/files/overview#limits) for sizes and expiry.
</Accordion>


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