File Upload API Design: Presigned URLs, Multipart and Resumable Uploads

Your servers become a slow, expensive pipe, which is the first thing file upload API design must prevent. Every byte travels from the phone to your API and then again to storage. One dropped connection throws the whole upload away.

Picture a common setup. A coaching app lets teachers upload recorded lectures of 1 to 3 GB and lets students upload homework PDFs of a few MB. The app is made up, but the problems are real.

A teacher on a 10 Mbit/s home connection needs about 43 minutes to send a 3 GiB lecture (made-up speed, real maths). If the connection drops at 90 percent, a plain upload starts again from zero, so 2.7 GiB is sent twice.

Meanwhile your API server holds a connection open for 43 minutes, buffers data and carries every byte twice. This guide fixes three problems in turn: the slow pipe, the restart from zero and the files you cannot trust.

Six words carry this whole guide. Each one gets a plain meaning here, tied to the coaching app.

• Object storage: a service that stores files as whole objects under a name called a key, such as incoming/teacher-3/lecture.mp4. Amazon S3 is the example used here; most clouds have a similar service.
• Presigned URL: a link to one storage action, signed with your server's secret key. Whoever holds the link can do that one action until it expires.
• Multipart upload: sending one big file as numbered pieces called parts, then asking storage to join them into one object.
• ETag: a short fingerprint that storage returns for each stored part or object. You hand the part ETags back when you finish, so storage knows which pieces to join.
• Offset: how many bytes of a file the server has safely received so far. A resumable upload continues from the offset instead of from zero.
• Quarantine: a separate area, such as a key prefix like incoming/, where new files wait until checks pass. Nothing in quarantine is shown to other users.

Good file upload API design splits an upload into three calls. The client asks your API to start, sends the bytes straight to storage, then tells your API it has finished.

Your API never carries the file bytes during the upload. It decides who may upload what, signs permission, records the upload in a database, and checks the result at the end. Storage does the heavy lifting it was built for.

Here is what the start call might return for a lecture. The API picked the key, the part size and the expiry; the client picked nothing that matters for security.

{
  "uploadId": "upl_7f3a",
  "method": "multipart",
  "key": "incoming/teacher-3/0b9c-lecture.mp4",
  "partSize": 16777216,
  "partUrls": [
    "https://STORAGE-HOST/...part 1 URL...",
    "https://STORAGE-HOST/...part 2 URL..."
  ],
  "expiresInSeconds": 3600
}

Keep an uploads table in your own database with the key, the owner, the declared size, the state and the created time. Storage knows about bytes; only your database knows which upload belongs to which teacher.

A presigned URL carries its own permission. Your server signs the bucket, the key, the action and an expiry time with its secret key, and storage checks that signature on every request.

Think of it like a parcel locker code. The shop gives you a code that opens one locker, for one delivery, until a set time. You never get the key to the whole locker bank.

Where the picture breaks: a locker code usually works once, but a presigned URL works as many times as you like until it expires. The S3 docs say so directly, and our test reused one URL without trouble.

What the signature locks

We ran presigned PUT URLs against LocalStack 4.14.0, an S3 emulator, with signature checks switched on. Anything inside the signature could not be changed by the client.

The last row is the quiet danger. If you do not sign the type, a student can store a homework file as a web page, and anyone who opens it may get HTML instead of a PDF.

How long a presigned URL can live

On S3, X-Amz-Expires, the expiry setting inside the URL, runs from 1 to 604,800 seconds, which is 7 days, as of 26 October 2026. The SDKs allow up to 7 days, while the S3 console allows 1 minute to 12 hours.

The URL also dies early if the credentials that signed it expire. The S3 docs say a URL signed with role credentials dies when the role session ends, even if you asked for longer. On an EC2 virtual server, that is typically 6 hours.

For uploads, keep expiry short: 10 to 15 minutes for a small file, and about an hour per batch of part URLs. If a teacher's upload outlives that, your API can sign fresh part URLs for the parts still missing.

Enforce limits in the signature, then verify the stored file. The client's own claims about name, size and type are hints, never proof.

Size: sign it with a POST policy

S3 also accepts browser-style form uploads with a POST policy. This is a signed JSON document of rules, and its content-length-range rule sets the smallest and largest allowed size in bytes.

Here is the homework start call in Python with boto3, the AWS software development kit (SDK) for Python. It signs a 10-minute form upload for one PDF of at most 10 MiB, under a key the server chose.

import uuid
import boto3
from botocore.config import Config

# Signs with your server's own AWS credentials, using Signature Version 4
s3 = boto3.client("s3", config=Config(signature_version="s3v4"))
BUCKET = "coaching-uploads"
MAX_PDF = 10 * 1024 * 1024  # 10 MiB


def create_homework_upload(user_id: str):
    key = f"incoming/{user_id}/{uuid.uuid4()}.pdf"  # server picks the name
    post = s3.generate_presigned_post(
        Bucket=BUCKET,
        Key=key,
        Fields={"Content-Type": "application/pdf"},
        Conditions=[
            {"Content-Type": "application/pdf"},
            ["content-length-range", 1, MAX_PDF],
        ],
        ExpiresIn=600,  # 10 minutes
    )
    return {"key": key, "url": post["url"], "fields": post["fields"]}

We ran this code against LocalStack. A small PDF got 204 No Content, which means success. An 11 MiB file got 400 EntityTooLarge, and changing the Content-Type field to text/html got 403 AccessDenied.

For a presigned PUT instead of a form, you can sign Content-Length, as the table showed. That pins one exact size, so the client must send its real size in the start call.

Type: check the bytes, not the label

The Content-Type header and the file extension are both chosen by the client. The OWASP File Upload Cheat Sheet says plainly not to trust the Content-Type header, because it can be spoofed.

A better check reads the file's first few bytes, often called magic bytes. A PDF should begin with %PDF-, and most MP4 files have the letters ftyp at byte 4. A ranged GET fetches just those bytes.

SIGNATURES = {
    "application/pdf": (0, b"%PDF-"),
    "image/png": (0, b"\x89PNG\r\n\x1a\n"),
    "video/mp4": (4, b"ftyp"),
}


def detected_type(key: str):
    head = s3.get_object(Bucket=BUCKET, Key=key, Range="bytes=0-15")["Body"].read()
    for mime, (offset, magic) in SIGNATURES.items():
        if head[offset:offset + len(magic)] == magic:
            return mime
    return None  # unknown: reject or send for manual review

This continues the homework snippet, reusing s3 and BUCKET. In our run it fetched only 16 bytes and got status 206, partial content. A file named renamed.pdf that really started with other bytes came back as unknown.

OWASP warns that magic bytes alone are easy to fake, so treat this as one layer. Pair it with an allow-list of extensions, server-chosen file names and the virus scan covered later.

A multipart upload sends a big file as numbered parts and joins them at the end. It has three steps: create the upload to get an upload ID, upload each part, then complete with every part's number and ETag.

The S3 docs recommend it for objects of 100 MB or more. A single PUT tops out at 5 GB, so bigger files must use parts anyway.

The maximum object size is stated two ways. The limits table says 48.8 TiB, which matches 10,000 parts of 5 GiB (48.83 TiB). The December 2025 announcement and the upload page say 50 TB.

Picking a part size

The part count caps your file size. With the minimum 5 MiB parts, 10,000 parts only reach 48.83 GiB. A 100 GiB file needs parts of at least 10.24 MiB.

The boto3 upload helper starts at 8 MiB parts and, in s3transfer 0.14.0, doubles the size until the count fits. In our run, a 100 GiB file got 16 MiB parts and a 1,000 GiB file got 128 MiB parts.

For the coaching app, 16 MiB parts are a fair middle. A failed part costs at most 16 MiB of resending, not 2.7 GiB, and parts can go up two or three at a time on a good connection.

What the parts rules look like when you break them

Pause and predict before reading on. If a phone sends part 3 first, then 1, then 2, will the final video be scrambled?

No. The docs say parts can be uploaded independently and in any order, and S3 joins them in ascending part number. Our LocalStack run sent parts 3, 1, 2 and got a correct 10,486,760-byte file.

Then we broke each rule on purpose in the same LocalStack run. The error names match the ones the S3 API reference lists.

• Re-uploading a part number overwrites the earlier part. New bytes give a new ETag, so keep the ETag from the latest upload.
• Completing with parts listed out of order failed with 400 InvalidPartOrder.
• Completing with an old ETag for a part failed with 400 InvalidPart.
• A 1 MiB part was accepted when uploaded, but completing failed with 400 EntityTooSmall because it was not the last part. The rule is enforced at the end, not at the start.
• Part number 10,001 and part number 0 were both rejected with 400 InvalidArgument.

What just happened? The rules live at the complete step. A client can upload broken pieces for an hour and only learn at the end. So set a valid part size in your start call, and check what arrived before you complete.

Uploading parts from a browser or phone

Your API can presign one URL per part, so the parts go straight to storage too. This sketch continues the homework snippet, reusing s3, BUCKET and uuid.

PART_SIZE = 16 * 1024 * 1024  # 16 MiB
MAX_LECTURE = 4 * 1024**3  # 4 GiB


def start_lecture_upload(user_id: str, size: int):
    if size not in range(1, MAX_LECTURE + 1):
        raise ValueError("lecture must be between 1 byte and 4 GiB")
    key = f"incoming/{user_id}/{uuid.uuid4()}.mp4"
    mpu = s3.create_multipart_upload(Bucket=BUCKET, Key=key, ContentType="video/mp4")
    count = -(-size // PART_SIZE)  # ceiling division
    urls = [
        s3.generate_presigned_url(
            "upload_part",
            Params={"Bucket": BUCKET, "Key": key,
                    "UploadId": mpu["UploadId"], "PartNumber": n},
            ExpiresIn=3600,
        )
        for n in range(1, count + 1)
    ]
    return {"key": key, "uploadId": mpu["UploadId"],
            "partSize": PART_SIZE, "partUrls": urls}


def complete_lecture_upload(key: str, upload_id: str, size: int):
    pages = s3.get_paginator("list_parts").paginate(
        Bucket=BUCKET, Key=key, UploadId=upload_id)
    parts = [p for page in pages for p in page.get("Parts", [])]
    if sum(p["Size"] for p in parts) != size:
        raise ValueError("uploaded bytes do not match the declared size")
    done = s3.complete_multipart_upload(
        Bucket=BUCKET, Key=key, UploadId=upload_id,
        MultipartUpload={"Parts": [
            {"PartNumber": p["PartNumber"], "ETag": p["ETag"]} for p in parts]},
    )
    return done["ETag"]

The complete call asks storage which parts really arrived, with ListParts, and refuses if the bytes do not add up to the declared size. In our run, a client that declared 20 MiB but sent 17 MiB was refused.

The check cannot be dodged by swapping a part afterwards. The complete call names each part's ETag, and a part replaced after the check fails with InvalidPart, as in our earlier run.

A browser needs one more setting. CORS is the browser rule for which other sites a page may call and which reply headers it may read. ETag is not on the Fetch standard's default list.

So add ETag to the ExposeHeaders list in your bucket's CORS settings. Without it, your web page uploads every part but cannot read the ETags it needs to finish.

The final multipart ETag in our run looked like a hash of the part hashes followed by -3, for three parts. The S3 docs only call it a checksum of checksums. Undocumented as of 26 October 2026, so never parse it.

Finish with one complete call that you can safely retry, cancel with abort, and set a lifecycle rule to clean up the uploads everyone forgot. Until one of those happens, S3 stores and bills the parts.

Completing without surprises

The S3 docs warn that completing can take several minutes. They also say a 200 OK reply can contain an error, so code that calls the API directly must read the response body. The botocore 1.40.76 source turns such a reply into a 500 and retries it.

Retries need care. On LocalStack, a second complete after a successful one returned 404 NoSuchUpload, because the upload ID no longer existed. Before treating that as failure, send a HEAD request, which fetches only the object's details, to see if the file exists.

Two optional guards help. Sending the expected total size as MpuObjectSize makes S3 reject a mismatch with 400 InvalidRequest. Sending If-None-Match with an asterisk refuses to overwrite a key that already exists, with 412.

Aborting and the forgotten uploads

Abort frees the parts. It returned 204 No Content in our run, and after that every call with the upload ID returned NoSuchUpload.

One catch comes from the S3 docs. Part uploads still in flight might succeed after an abort, so you may need to abort more than once and confirm with ListParts that no parts remain.

The bigger risk is silence. A teacher closes the app at 60 percent and never returns. In our emulator test, the parts did not show up in a normal object listing. The S3 docs say they are billed until the upload is completed or aborted.

The fix is a bucket lifecycle rule with the AbortIncompleteMultipartUpload action. Any upload not completed within a set number of days becomes eligible for abort, and S3 then deletes its parts. Finished objects are never touched.

{
  "Rules": [
    {
      "ID": "abort-stale-uploads",
      "Status": "Enabled",
      "Filter": {
        "Prefix": "incoming/"
      },
      "AbortIncompleteMultipartUpload": {
        "DaysAfterInitiation": 7
      }
    }
  ]
}

Run a matching sweep in your own database too. Mark rows still in the uploading state after the same number of days as expired, so your records agree with storage.

An upload is resumable when the client can ask how many bytes the server already has and send only the rest. The tus protocol is an open standard that defines exactly those messages over plain HTTP.

S3 multipart is already resumable at part level. After a crash, the client calls ListParts, sees which part numbers exist and sends the missing ones. Tus goes finer, down to the byte. It runs through your own tus server, which can save to disk or to object storage.

Tus 1.0.0, dated 25 March 2016, is the current version as of 26 October 2026. It uses three core requests plus a creation extension.

1. 1

   Create the upload

   The client sends POST with Upload-Length, the total size in bytes. The server answers 201 Created with a Location header, the upload's own URL.

2. 2

   Send bytes with PATCH

   The client sends PATCH with Upload-Offset, where these bytes start, and the type application/offset+octet-stream. The server answers 204 with the new offset.

3. 3

   After a drop, ask with HEAD

   The client sends HEAD to the upload URL. The server answers with Upload-Offset, the bytes it really has, and Cache-Control no-store so no cache serves an old answer.

4. 4

   Continue from that offset

   The client sends PATCH from the returned offset. If its offset is wrong, the server answers 409 Conflict and changes nothing.

5. 5

   Cancel if needed

   With the termination extension, DELETE on the upload URL answers 204 No Content, and the server frees the stored bytes.

We ran this exact exchange against @tus/server 2.4.6, the project's Node.js server, using curl. The stored file came out byte for byte correct, and the server answered 413 to a creation larger than its Tus-Max-Size.

One small gap showed up. A PATCH with the wrong content type got 400 Bad Request, while the spec says a server should answer 415. So do not code a client to expect exactly 415 for that mistake.

Other tus extensions cover checksums per chunk, with status 460 when a chunk does not match, expiry of unfinished uploads, and joining parallel uploads. A server lists the ones it supports in the Tus-Extension header of an OPTIONS reply.

It is a proposed HTTP standard for resumable uploads, grown out of tus and worked on by the IETF HTTP working group. As of 26 October 2026 it is still an Internet-Draft, a working document, not an RFC, the IETF's published standard form.

The ideas will feel familiar. An Upload-Complete header says whether a request carries the last byte, Upload-Offset reports progress, HEAD asks for the offset, PATCH appends, and DELETE cancels.

One part is new. An interim 104 response, an early provisional reply named Upload Resumption Supported, can tell the client its upload URL before the first request finishes. Limits move into one Upload-Limit header, with keys such as max-size and max-age.

The 104 status number is only a suggested value in the draft. Treat everything here as what is coming, not what to ship.

Keep every new file in quarantine and let storage raise an event when it lands. A worker scans it and only then moves it to where users can reach it. Your API serves files from the clean area only.

On S3, an event such as s3:ObjectCreated:CompleteMultipartUpload or s3:ObjectCreated:Post can go to a queue, a topic, a function or an event bus. The worker pulls the event and scans the object.

The S3 docs say these events arrive at least once, not always in order, and rarely twice. So the scan worker must be idempotent: scanning the same file twice should give the same result and no double side effects.

1. 1

   Land in quarantine

   Signed keys always start with incoming/. Bucket rules stop anyone outside your backend from reading that prefix.

2. 2

   Raise an event

   Storage sends an object-created event to a queue. The worker records the key in the uploads table, so duplicates are spotted.

3. 3

   Check, then scan

   Check the size and magic bytes first, then run an antivirus engine such as ClamAV, an open-source scanner. OWASP also suggests a sandbox or content disarm for PDF and Office files.

4. 4

   Promote or reject

   A clean file is copied to clean/ and the quarantine copy is deleted. A bad file is tagged and kept for review, and the upload row moves to rejected.

5. 5

   Tell the user

   The app polls the upload row, or your backend calls the app's server back with a webhook. Until then, show the file as processing, not as ready.

We tested the promote step on LocalStack: tag the object scan=clean, copy it to clean/ with its tags, then delete the original. The copy kept the tag and the quarantine key was gone.

Archives need extra care. OWASP lists zip bombs, small files that expand to huge ones, and says size limits should be checked after decompression. Many apps simply refuse archives.

To check your pipeline end to end, upload the EICAR test file, a harmless file that antivirus tools are built to flag. It should end in the rejected state, never in clean/.

Lead with the split: your API owns permission and records, storage owns bytes. Then walk one large file through its life, as below.

1. 1

   State the needs

   Files from KB to many GB, flaky mobile networks, untrusted content and no app servers in the data path.

2. 2

   Start call

   The API checks the user and the declared size and type, picks the key and returns presigned URLs with short expiry.

3. 3

   Direct upload

   Small files go up in one signed PUT or POST. Big files go in parts of about 16 MiB, in parallel, resumable per part.

4. 4

   Complete call

   The API lists the parts, checks the total size, completes the upload and makes retries safe.

5. 5

   Quarantine and scan

   Storage events drive an idempotent scan worker. Only clean files move to the readable area.

6. 6

   Cleanup and limits

   A lifecycle rule aborts stale uploads after 7 days. Name the S3 limits: 10,000 parts, 5 MiB to 5 GiB each, URLs up to 7 days.