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

# Direct uploads

> Send a file straight to storage, up to your plan's ceiling, then pass its upload_id to any run. One PUT up to 100 MB, parts above.

A file sent in a request body stops at **100 MB**, whatever the plan. A direct upload has no such limit: the bytes go from you to storage, and only the start and the finish pass through the API. Use it for a file on your own disk that is bigger than 100 MB, or whenever you would rather not hold a connection open while a run starts.

Three calls:

1. `POST /api/v1/uploads` — say what the file is. You get back where to send it.
2. `PUT` the bytes to the URL, or to each part's URL.
3. `POST /api/v1/uploads/{id}/complete` — we check the file and answer with what it turned out to be.

Then send its `upload_id` to [`/run/{skill}`](https://docs.mediamonster.app/api/run-skill), [`/runs`](https://docs.mediamonster.app/api/runs) or [`/convert`](https://docs.mediamonster.app/api/convert) in place of `file` or `url`. An upload can be run as many times as you like.

Opening and completing an upload needs a key with the `run` [scope](https://docs.mediamonster.app/api/authentication.md#scopes). Reading one back needs `read`.

## Open an upload

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/uploads \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "shoe.png", "content_type": "image/png", "size_bytes": 3145728}'
```

| Field | Type | What it does |
| - | - | - |
| `file_name` | string | The file's name. Its extension has to match `content_type` |
| `content_type` | string | The file's type, e.g. `video/mp4`. Left empty, it is read from the extension |
| `size_bytes` | integer | The file's exact size. The file that arrives has to be this size |

The file is held to your plan before any byte moves: a type we take, and a size under your plan's [ceiling](https://docs.mediamonster.app/formats.md#size-ceilings). Over it is `413 file_too_large`, and the message names the plan that takes it.

### Up to 100 MB: one PUT

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "upload_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "method": "PUT",
  "url": "https://…r2.cloudflarestorage.com/…",
  "headers": { "content-type": "image/png" },
  "size_bytes": 3145728,
  "kind": "image",
  "mime": "image/png",
  "expires_at": "2026-09-26T18:00:00.000Z",
  "complete_url": "/api/v1/uploads/0f8fad5b-d9cb-469f-a165-70867728950e/complete"
}
```

Send the file with the `headers` given — the type is part of the signature, so a PUT without it is refused. So is its length: the body has to be exactly `size_bytes`. Every HTTP client sets `Content-Length` from the body on its own; a chunked PUT, with no length, is refused.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X PUT "$URL" -H "content-type: image/png" --data-binary @shoe.png
```

### Over 100 MB: parts

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "upload_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "method": "PUT",
  "part_size": 5242880,
  "parts": [
    { "part_number": 1, "url": "https://…" },
    { "part_number": 2, "url": "https://…" }
  ],
  "size_bytes": 1073741824,
  "kind": "video",
  "mime": "video/mp4",
  "expires_at": "2026-09-26T18:00:00.000Z",
  "complete_url": "/api/v1/uploads/0f8fad5b-d9cb-469f-a165-70867728950e/complete"
}
```

Cut the file into `part_size` slices — every part that size except the last — and `PUT` slice *n* to part *n*'s URL. Parts can go in any order and several at once. Keep the `ETag` header each PUT answers with; `complete` needs them.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
split -b 5242880 -d -a 5 interview.mp4 part-
curl -X PUT "$PART_1_URL" --data-binary @part-00000 -D - | grep -i etag
```

A single PUT's URL lasts an hour; part URLs last six hours (`expires_at`). An upload that runs past that is opened again. Complete it within a day of the last PUT: bytes never completed are cleared after that.

## Complete it

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/uploads/0f8fad5b-…/complete \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"parts": [{"part_number": 1, "etag": "\"a54357aff0632cce46d942af68356b38\""}, …]}'
```

A single PUT sends no body. Parts send every `part_number` with its `etag`, once each.

The file is then checked the way every upload is: its real type, read from its bytes, and its real size against your plan. What it turned out to be comes back:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "upload_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "ready",
  "file_name": "interview.mp4",
  "kind": "video",
  "mime": "video/mp4",
  "size_bytes": 1073741824,
  "duration_seconds": 1834.2,
  "width": 1920,
  "height": 1080,
  "created_at": "2026-09-26T12:00:00.000Z"
}
```

A file that fails the check is deleted. Completing twice answers the same as the first time.

The URLs write to a holding place, not to the file itself. `complete` moves what arrived into place once, and the file you run is the one it checked: a PUT to the same URL afterwards changes nothing.

## Run it

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/run/captions \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "0f8fad5b-d9cb-469f-a165-70867728950e"}'
```

Each run gets a job of its own and reads the same stored file, so running a second skill over an upload leaves the first one's results alone.

## Read one back

`GET /api/v1/uploads/{id}` answers the same shape, with `"status": "pending"` until the upload is completed.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `missing_file_name` | No `file_name` |
| 400 | `bad_size` | `size_bytes` missing, or not a whole number of bytes |
| 400 | `bad_file` | Under the 64-byte floor, or the bytes aren't the declared type. The file is deleted |
| 415 | `unsupported_media` | A type we don't take, or an extension that doesn't match it |
| 413 | `file_too_large` | Over the plan's ceiling, declared or as it arrived |
| 400 | `missing_parts` | A multipart `complete` with no `parts` |
| 400 | `bad_parts` | A part missing, sent twice, or without an `etag` |
| 400 | `upload_incomplete` | The parts didn't fit together — a part not sent, or a wrong `etag` |
| 409 | `upload_unfinished` | `complete` before the PUT landed, or a run given an upload that isn't complete |
| 409 | `upload_completing` | Another `complete` for this upload is running. Ask again in a moment |
| 404 | `upload_not_found` | No upload with that id on this account |
| 400 | `bad_upload_id` | `upload_id` isn't a UUID |
| 503 | `upload_unavailable` | Storage wouldn't open the upload. Try again shortly |


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