PercentURL / File encoding

Should You URL Encode a File? Uploads vs Text Values

Choose the right place for file bytes, filenames, and small binary values instead of turning an entire file into a URL string.

Quick answer: Usually, do not percent-encode a file’s bytes into a URL. Send a file in the request body with the format the endpoint expects—commonly multipart/form-data. Percent-encode only a filename or other text value when it belongs in a URL component. Use Base64url only when the receiving API explicitly asks for that text representation.
Encode a filename or text value

“URL encode a file” can mean three different things: encode its contents, encode its name, or upload the file to a web service. Those are different jobs. The wrong choice can produce an oversized string or a request the server does not understand.

Choose by what the server expects

Your taskWhere the data goesUse this
Upload a document, image, or other fileHTTP request bodyThe endpoint’s documented upload format, often multipart/form-data
Put a filename, search term, or label in a URLOne path or query componentPercent-encode that text value; preserve the URL’s separators
Send bytes through an API field that accepts text onlyA text field in the API’s defined payloadUse the exact encoding the API specifies, such as Base64url
Share a file with someoneA URL that identifies a stored resourceUpload the file, then share its link; do not put the file contents in the link

Uploading a file is not URL encoding

For a browser form upload, multipart/form-data puts the file in a request body as a part. The part can carry a filename and a media type; it is separate from the page URL. RFC 7578 defines this format and its parts. The server’s API documentation decides whether to use multipart, a raw binary body, or another upload method.

<form method="post" enctype="multipart/form-data">
  <input type="file" name="file">
  <button type="submit">Upload</button>
</form>

This form is a shape example only; it has no destination or server implementation. A real upload must use the endpoint supplied by your service.

Encode a filename only when it becomes URL text

If a URL needs a filename such as quarterly report #2.csv, treat the filename as one path segment or query value. Encode the text for that context, then assemble it into the URL. Do not encode https://, the entire path, or query separators as though they were part of the filename. See the URL encoder guide for component boundaries.

File names inside an upload header are a separate format again. Do not copy a URL-encoded filename into an upload header unless that upload protocol tells you to; follow the endpoint’s filename rules.

When Base64url is the right choice

Some APIs require binary bytes to be represented as text inside JSON or another text-only field. In that case, follow the API’s specified encoding. Base64url uses a URL- and filename-safe alphabet in place of standard Base64’s + and /; padding rules depend on the receiving format. It is still an encoding, not encryption. Percent-encoding and Base64url are not interchangeable.

For example, the three bytes 00 7F FF can be written as percent-encoded bytes %00%7F%FF, standard Base64 AH//, or Base64url AH__. In this specific example, the percent form occupies 9 visible characters and each Base64 form 4. The service must decode the same representation you send. For a browser-based Base64 tool, see Base64 Encoder / Decoder.

What PercentURL can encode

The PercentURL encoder accepts text; its current page does not provide a file picker or file-upload workflow. Use it for a textual filename, query value, or other text that belongs in a URL—not for a file’s raw contents. If a service requires a file, use that service’s upload endpoint and its documented request format.

Before you send the request

References