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

# present_public_file

> Present a public file as a download card in the chat.

# present\_public\_file

Presents a public file as a downloadable card in the chat. Use this when a user asks for a file or when you want to offer a document for download.

Requires the file to exist in the agent's public data (uploaded via the **Data → Public** tab in the dashboard).

## Parameters

| Name          | Type   | Required | Description                                                                            |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `filename`    | string | yes      | The exact filename of the public file to present. Case-sensitive, including extension. |
| `description` | string | no       | Short description rendered alongside the download card.                                |

## Returns

```json theme={null}
{
  "action": "download",
  "filename": "user-guide.pdf",
  "description": "User guide v3",
  "size": 1843291,
  "downloadUrl": "https://cdn.../user-guide.pdf?..."
}
```

On failure (file not in manifest, missing from storage, or presign error):

```json theme={null}
{
  "error": "present_public_file failed: file not found.",
  "details": {
    "filename": "user-guide.pdf",
    "available_public_files": ["quickstart.pdf", "faq.md", "pricing.pdf"],
    "hint": "Use one of the filenames listed in available_public_files."
  }
}
```

The agent can retry with the correct filename from `available_public_files`.

***

## Examples

### Offer a single document

```json theme={null}
{ "filename": "refund-policy.pdf" }
```

### Offer a document with context

```json theme={null}
{
  "filename": "integration-guide.pdf",
  "description": "Step-by-step guide for connecting your CRM"
}
```

### Offer different files based on the user's plan

Add a rule to your agent's configuration:

```text theme={null}
When a user asks for the API docs, present api-docs-pro.pdf for Pro users
and api-docs-free.pdf for Free users. Read the user's plan from memory first.
```

The agent calls:

```json theme={null}
{ "filename": "api-docs-pro.pdf", "description": "Full API reference (Pro)" }
```

***

## Call from your own custom tool

```js theme={null}
export async function handle(input, ctx) {
  return await ctx.tools.present_public_file({
    filename:    input.doc_name,
    description: input.doc_label ?? 'As requested',
  });
}
```

```python theme={null}
async def handle(input, ctx):
    return await ctx.tools.present_public_file({
        'filename':    input['doc_name'],
        'description': input.get('doc_label', 'As requested'),
    })
```

## Notes

* Only registered when the agent has at least one file in `data_public`.
* Filenames are matched exactly (case-sensitive, including extension).
* Download links are short-lived and expire automatically.
* For binary files that should be shown inline rather than downloaded, use [`show_image`](/builtin-tools/show_image). For displaying text file contents inline, use [`show_file_excerpt`](/builtin-tools/show_file_excerpt). For files generated at runtime, use [`surface_file`](/builtin-tools/surface_file).