# API File Uploads Downloads

> Design file upload and download APIs: multipart vs presigned vs resumable, Range/206 downloads, Content-Disposition, and content validation. Use when adding binary transfer endpoints or reviewing upload security.

- Skill: `deangrant/api-file-uploads-downloads` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-file-uploads-downloads`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-file-uploads-downloads/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-file-uploads-downloads

---


# File Uploads and Downloads

Use this skill when transferring **binary assets** through or alongside the API.

---

## 1. Size-based upload strategy

| Size | Mechanism |
| ---- | --------- |
| < ~1MB | Base64 in JSON (overhead) |
| ~1–100MB | `multipart/form-data` |
| > ~100MB | Presigned direct-to-storage PUT |
| Unreliable large | Resumable chunks |

Presigned: short-lived scoped URL; client uploads; notify API on complete.

**PUT must not carry `Content-Range`** (RFC 9110 → 400) — use PATCH or a
dedicated upload protocol for partial writes.

---

## 2. Downloads

Stream in chunks — never buffer whole files in RAM. Support
`Accept-Ranges: bytes` → `Range` → **206** + `Content-Range` (416 if unsatisfiable).

`Content-Disposition: attachment|inline; filename=...; filename*=UTF-8''...`

---

## 3. Security

Validate **magic bytes** (not client Content-Type alone); rate-limit uploads;
malware scan; sanitize filenames (`../`). Errors: **413**, **415**, problem+json.

---

## 4. Quick checklist

- [ ] Mechanism matches size profile.
- [ ] Stream downloads; Range for large assets.
- [ ] Content-Disposition set appropriately.
- [ ] Content-based type validation; 413/415.
- [ ] Limits documented in OpenAPI.

See [reference.md](reference.md) and [examples.md](examples.md).