multipart/form-data Multipart Form Data Flagship

What it's for

multipart/form-data encodes an HTTP request body as a series of distinct "parts," each with its own headers and content — the format required whenever an HTML form includes a file upload (<input type="file">), because unlike application/x-www-form-urlencoded, it can carry raw binary content alongside regular text fields in the same request.

Every file upload endpoint you've ever used — profile picture uploads, document attachments, drag-and-drop file inputs — relies on this format under the hood, whether submitted from a plain HTML form or constructed programmatically via FormData in JavaScript.

Format & syntax

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="username"

alice
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

(binary image data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

• The boundary parameter in the Content-Type header defines a unique delimiter string that separates parts — it must not appear anywhere within the actual content, so it's typically a long, randomly generated string
• Each part has its own Content-Disposition: form-data; name="..." header identifying the field name, plus filename and Content-Type for file parts specifically
• The final boundary line has trailing -- to mark the end of the body

How it's used in practice

• File upload forms — any HTML form with enctype="multipart/form-data" and a file input, submitting both regular text fields and binary file content together in one request.
• JavaScript FormData API — new FormData() in browser JavaScript automatically constructs a properly formatted multipart body, letting you build upload requests programmatically (via fetch or XMLHttpRequest) without manually handling boundaries or encoding.
• API file upload endpoints — REST APIs that accept file uploads (avatar images, document attachments, CSV imports) typically expect multipart/form-data specifically for the upload endpoint, even if the rest of the API uses JSON elsewhere.
• Mixed text-and-file submissions — forms that combine metadata (a caption, a category, a description) with a file upload in a single submission rely on multipart's ability to carry both structured text and binary data together.

Common mistakes & gotchas

• Manually setting the Content-Type header when using FormData — if you're using the JavaScript FormData API with fetch, don't manually set Content-Type: multipart/form-data yourself; the browser needs to generate and include the correct boundary parameter automatically, and manually setting the header without a boundary breaks parsing entirely. Let the browser set it.
• File size limits catching people off guard — many servers, load balancers, and frameworks have default request body size limits that are too small for larger file uploads, requiring explicit configuration changes for endpoints expected to handle bigger files.
• Not validating uploaded file content, only the declared type — the Content-Type within an individual part (like image/jpeg on a file part) is client-supplied and not verified by the format itself; genuine content validation (magic byte checking, virus scanning) needs to happen server-side regardless of what the multipart body claims.
• Confusing multipart/form-data with multipart/mixed or other multipart subtypes — multipart is actually a family of related formats (multipart/mixed, multipart/alternative, multipart/form-data, etc.) used in different contexts (email being another major consumer of multipart formats); form-data specifically is the one relevant to HTML form/file upload submissions.

Comparison & FAQ

Why shouldn't I manually set the Content-Type header when using FormData?

The browser needs to generate a unique boundary value and include it in the header automatically as it constructs the multipart body — manually overriding the header without matching boundary logic will produce a malformed request the server can't parse.

Can I send JSON data alongside a file in the same request?

Yes — multipart/form-data lets you include both regular text/JSON-string fields and file parts in the same request; some APIs specifically expect a field like metadata containing a JSON string alongside a file field containing the actual upload.

What determines the maximum file upload size?

A combination of server configuration, framework-level limits, and any intermediate infrastructure (load balancers, reverse proxies, CDN) that might impose its own body size cap — hitting a size limit can happen at any of these layers, not just the application code itself.

Is multipart/form-data only used for file uploads?

Its primary modern use is file uploads, but the broader multipart family of MIME types (of which form-data is one member) is also used elsewhere, most notably in email (MIME originally stood for Multipurpose Internet Mail Extensions) for messages with multiple parts like an HTML body plus attachments.