---
name: upload-files
description: >
Upload local files or user attachments to the Gradio server and get back
public URLs. Use when: upload image, upload XML, upload attachment,
file to URL, host file, upload for HTR, upload for viewer, prepare files
for transcription, upload document images.
---
# Upload Files
Upload local files or user-provided attachments (images, XML, etc.) to the
Gradio server so they become publicly accessible URLs. These URLs can then
be passed to tools like `htr_transcribe` or the document viewer.
## When to use
- User has attached images or XML files in the conversation
- User has local file paths that need to be accessible by a remote tool
- Any tool requires http/https URLs but you only have local data
If you already have http/https URLs (e.g. IIIF links, public image URLs),
skip this skill entirely and pass them directly to the target tool.
## Server URL
The upload target is the Gradio Space that backs the HTR MCP server:
```
https://riksarkivet-htr-demo.hf.space
```
Override with the `HTR_SPACE_URL` environment variable if set.
## Upload workflow
### Step 1: Save attachments to disk
If the user attached files in the conversation (not already on disk), save
them first. Claude attachments are available as content in the conversation
— write them to temporary files.
### Step 2: Upload each file
For each file, POST to the Gradio upload endpoint:
```bash
curl -s -X POST "https://riksarkivet-htr-demo.hf.space/gradio_api/upload" \
-F "files=@/path/to/filename.jpg"
```
Response is a JSON array of server paths:
```json
["/tmp/gradio/abc123def/filename.jpg"]
```
### Step 3: Construct public URLs
For each server path returned, construct the public URL:
```
https://riksarkivet-htr-demo.hf.space/gradio_api/file=/tmp/gradio/abc123def/filename.jpg
```
Pattern: `{base_url}/gradio_api/file={server_path}`
### Step 4: Collect all URLs
Gather all constructed URLs before passing them to the target tool.
Present the URLs to the user so they can verify the uploads succeeded.
## Batch upload
You can upload multiple files in a single request:
```bash
curl -s -X POST "https://riksarkivet-htr-demo.hf.space/gradio_api/upload" \
-F "files=@page1.jpg" \
-F "files=@page2.jpg" \
-F "files=@page3.jpg"
```
Response:
```json
[
"/tmp/gradio/abc123/page1.jpg",
"/tmp/gradio/abc123/page2.jpg",
"/tmp/gradio/abc123/page3.jpg"
]
```
Prefer batch upload over individual uploads when possible.
## Supported file types
| Type | Extensions | Use with |
|------|-----------|----------|
| Images | `.jpg`, `.jpeg`, `.png`, `.tif`, `.tiff` | `htr_transcribe`, document viewer |
| ALTO XML | `.xml` | document viewer (text layer overlay) |
| PAGE XML | `.xml` | document viewer (text layer overlay) |
## After uploading
Once you have public URLs, pass them to the appropriate tool:
- **HTR transcription**: call `htr_transcribe` with `image_urls=[...]`
- **Document viewer**: call `view_document` with `image_urls=[...]` and optionally `text_layer_urls=[...]`
## Error handling
- **Connection error**: the Gradio Space may be sleeping. Retry after 30 seconds.
- **413 Payload Too Large**: file exceeds the server limit. Try uploading fewer files per request.
- **Empty response**: verify the file path is correct and the file exists.
