# Upload files

Two ways to put a file into Soontra: inline for small files, by upload URL for larger ones.

Both need the `write` scope. New files go to the Team drive unless the call says `drive_scope: "personal"`. Nothing can be uploaded into Shared with me.

## Small files: inline

`soontra_files_upload` takes the file as base64 in the call itself. The limit is 5 MB once decoded, but keep it under 3 MB: many AI apps cap the size of their own requests.

Arguments:

```json
{
  "filename": "brief.pdf",
  "content_base64": "JVBERi0xLjcK...",
  "mime_type": "application/pdf",
  "folder_id": "0f9c2c1e-6c3b-4a55-9d0e-2f6f1f7a1b10"
}
```

The result includes the new file and a `verification` block with its SHA-256 and size, so you can confirm what arrived. Pass your own `sha256` and the upload is refused if the bytes do not match.

## Larger files: upload URL

1. **Ask for an upload URL.** Call `soontra_files_createUploadUrl` with the file’s name, its exact size in bytes (up to 50 MiB) and its SHA-256.

```json
{
  "filename": "interview.mp4",
  "size_bytes": 41234567,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "mime_type": "video/mp4"
}
```

2. **Send the bytes.** The result has an `upload_url`, the `headers` to send and a ready `curl_template`. `PUT` the file to the URL within 15 minutes. The URL works once.

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @interview.mp4
```

3. **Complete the upload.** Call `soontra_files_completeUpload` with the `upload_id` from step one, within 60 minutes. Soontra checks the bytes against the size and hash you declared, then creates the file.

> **Note:** Completing the same upload twice is safe: the second call returns the same file with `already_completed`.

## A new version of a file

To replace a file and keep its history, use `soontra_files_uploadVersion` (inline), or pass `version_of_file_id` to `soontra_files_createUploadUrl`. The earlier copy moves to the file’s version history and can be restored in Soontra. Only the file’s owner or a manager can add a version.

## What happens to an upload

- CSV and XLSX files become Soontra spreadsheets.
- HEIC and HEIF images are refused. Convert them to JPEG or PNG first.
- A person can have 10 uploads waiting to be completed in a workspace at once.
- Uploads have their own [rate limits](https://soontra.com/docs/limits).