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

# Files

> Put a file in an open browser session for a page's file field, and list the files the session downloaded, each with a link that lasts 15 minutes.

Both calls are free and need a session that is still running. Uploads and downloads are removed when the session closes, so fetch what you need first.

## Upload

`POST /v1/browser/{session_id}/uploads` puts a file in the session under `name`. Send the bytes as `base64`, or a `url` for Stophy to fetch.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser/$SESSION_ID/uploads \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "notes.txt", "base64": "SGVsbG8gZnJvbSBTdG9waHk="}'
```

The answer has `name` and `size`. A `url` must open the file without signing in, and Stophy waits up to 30 seconds. Without `name`, the last part of the address is used.

To fill a file field, run [Execute](https://docs.stophy.dev/browser/execute.md) code that calls `setInputFiles('notes.txt')` on the file locator. A running session lists its uploads when you [read it](https://docs.stophy.dev/browser/overview#close-read-and-list).

| Field | Meaning |
| - | - |
| `name` | The name the page sees. Required with `base64`. |
| `base64` | The file's bytes, Base64 encoded |
| `url` | A public `http` or `https` address. Not with `base64`. |

A file is at most 20 MB, and a session takes at most 100 MB of uploads.

## Download

`GET /v1/browser/{session_id}/downloads` lists the files, sorted by name.

```json theme={null}
{
  "success": true,
  "files": [
    {
      "name": "report.txt",
      "size": 17,
      "contentType": "text/plain;charset=utf-8",
      "url": "https://api.stophy.dev/v1/browser/96aa4901-52b9-440a-9dab-5df9b53a5387/downloads/report.txt?expires=1794940294041&signature=…"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

| Query | Default | Meaning |
| - | - | - |
| `includeUrls` | `false` | `true` adds a `url` to each file up to 100 MB |
| `limit` | `50` | Files per page, 1 to 100 |
| `cursor` | none | `nextCursor` from the last page, while `hasMore` is `true` |

The link needs no API key, so a browser or download tool can use it. It stops working after 15 minutes. Read the list again for a new one.

## Errors

All return `400 invalidRequest` unless noted.

* A file over 20 MB.
* Both `base64` and `url`, or neither, or `base64` with no `name`.
* A `url` that does not answer with a success status. The message gives the status it got.
* A session that has ended: `410 notFound` on upload, and `409 invalidRequest` on the download list.


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