# Upload, list, download and delete files

This guide uses `curl` and the REST API, which works from any operating system, container or CI job. The [MCP server](https://strovio.xyz/docs/mcp) and the [SDK](https://strovio.xyz/docs/sdk) do the same things.

## Prerequisites

- An API key in `STROVIO_API_KEY`. See [Create an account and an API key](https://strovio.xyz/docs/get-an-api-key).
- `curl`. It ships with macOS, most Linux distributions and Windows 10 and 11 (as `curl.exe`).

On Windows PowerShell, write `curl.exe` instead of `curl` and `$env:STROVIO_API_KEY` instead of `$STROVIO_API_KEY`, and put each command on one line.

## Paths and keys

You choose a path when you upload, such as `reports/2026/q1.pdf`. Letters, numbers, dots, dashes, underscores and `/` are safest; percent-encode anything else in the URL, for example a space as `%20`. Do not start with `/` and do not use `..`.

Strovio stores the file under a full key: `uploads/<your account id>/<public or private>/<your path>`. Responses return that full key. To get, check or delete a file, send either the full key or exactly the path you uploaded to. If the same path exists as both a public and a private file, the path alone returns `409 ambiguous_key`; send the full key instead.

## 1. Upload

```bash
curl -X PUT "https://strovio.xyz/api/v1/files/reports/q1.pdf" \
  -H "Authorization: Bearer $STROVIO_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "X-Access: private" \
  --data-binary @q1.pdf
```

Windows PowerShell:

```powershell
curl.exe -X PUT "https://strovio.xyz/api/v1/files/reports/q1.pdf" -H "Authorization: Bearer $env:STROVIO_API_KEY" -H "Content-Type: application/pdf" -H "X-Access: private" --data-binary "@q1.pdf"
```

- `X-Access: public` gives the file a permanent public URL. Anything else, or no header, makes it private.
- Always set `Content-Type` to the file's media type. It is stored and returned when the file is downloaded. Without it, curl sends `application/x-www-form-urlencoded` and that is what gets stored.
- Uploading to a path that already exists with the same access replaces the file. Uploading it with the other access creates a second file at the same path; path-only requests then return `409 ambiguous_key`, so use the full key.

Expected result: status `201` and JSON like:

```json
{
  "key": "uploads/clx.../private/reports/q1.pdf",
  "name": "reports/q1.pdf",
  "size": 204800,
  "contentType": "application/pdf",
  "access": "private",
  "url": null,
  "createdAt": "2026-11-07T10:15:30.250Z"
}
```

For public files `url` is the permanent public URL. For files over about 100 MB, use [multipart uploads](https://strovio.xyz/docs/large-uploads); the limit for a single request is 512 MB.

## 2. List

```bash
curl "https://strovio.xyz/api/v1/files?prefix=reports/&limit=50" \
  -H "Authorization: Bearer $STROVIO_API_KEY"
```

- `prefix` returns only files whose key contains that text anywhere, so `reports/` also matches `old/reports/q1.pdf`. Check the `key` of each result before acting on it.
- `limit` is a whole number from 1. Values above 1000 are treated as 1000, which is also the default.
- Files come newest first in `objects`, with `count`.

## 3. Get a download URL

```bash
curl "https://strovio.xyz/api/v1/files/reports/q1.pdf" \
  -H "Authorization: Bearer $STROVIO_API_KEY"
```

Expected result: status `200` and JSON like:

```json
{
  "key": "uploads/clx.../private/reports/q1.pdf",
  "name": "q1.pdf",
  "size": 204800,
  "contentType": "application/pdf",
  "access": "private",
  "url": "https://s3.strovio.xyz/...&X-Amz-Expires=3600&...",
  "expiresIn": 3600,
  "createdAt": "2026-11-07T10:15:30.250Z",
  "updatedAt": "2026-11-07T10:15:30.250Z"
}
```

- Public files: `url` is the permanent public URL, and `expiresIn` is `null`.
- Private files: `url` is a signed URL valid for 3600 seconds (one hour), and `expiresIn` is `3600`. The lifetime is fixed; request a new URL when it expires. For a link that never expires, a person creates a [share link](https://strovio.xyz/docs/share-links).

Download it (`-f` makes curl fail instead of saving an error page if the URL has expired):

```bash
curl -fL -o q1.pdf "<url from the response>"
```

## 4. Check whether a file exists

```bash
curl -I "https://strovio.xyz/api/v1/files/reports/q1.pdf" \
  -H "Authorization: Bearer $STROVIO_API_KEY"
```

`200` means it exists, with `Content-Length`, `Content-Type`, `X-Access` and `Last-Modified` headers. `404` means it does not.

## 5. Delete

```bash
curl -X DELETE "https://strovio.xyz/api/v1/files/reports/q1.pdf" \
  -H "Authorization: Bearer $STROVIO_API_KEY"
```

Expected result: `{"ok":true,"key":"uploads/.../private/reports/q1.pdf"}`. Deleting is permanent and also removes the file's share links. Files deleted through the API do not go to the dashboard trash.

## The same steps in Windows PowerShell

```powershell
curl.exe "https://strovio.xyz/api/v1/files?prefix=reports/&limit=50" -H "Authorization: Bearer $env:STROVIO_API_KEY"
curl.exe "https://strovio.xyz/api/v1/files/reports/q1.pdf" -H "Authorization: Bearer $env:STROVIO_API_KEY"
curl.exe -fL -o q1.pdf "<url from the response>"
curl.exe -I "https://strovio.xyz/api/v1/files/reports/q1.pdf" -H "Authorization: Bearer $env:STROVIO_API_KEY"
curl.exe -X DELETE "https://strovio.xyz/api/v1/files/reports/q1.pdf" -H "Authorization: Bearer $env:STROVIO_API_KEY"
```

## Confirm success

Run step 4 for the path. After an upload it returns `200`; after a delete it returns `404`.

## Common errors

- `401 invalid_api_key`: see [Create an account and an API key](https://strovio.xyz/docs/get-an-api-key).
- `404 file_not_found`: the path or key does not match a file. List with `prefix` to find the exact key.
- `409 ambiguous_key`: a public and a private file share the path. Use the full key.
- `413 file_too_large`: the body is over 512 MB.
- `413 storage_quota_exceeded`: delete files or upgrade at [strovio.xyz/billing](https://strovio.xyz/billing).
- On Windows, `Invoke-WebRequest : A parameter cannot be found`: you ran `curl` instead of `curl.exe`.

All codes are listed on [Errors](https://strovio.xyz/docs/errors).

---

Source: https://strovio.xyz/docs/upload-and-download
All docs for agents: https://strovio.xyz/llms.txt