REST File Upload API: Working Examples and a Public URL

· · 10 min read

Most applications do not need a complicated upload stack to get started. A multipart POST with an API key can return a public URL in one response, and the rest of the design depends on how you handle limits, access, deletion, and delivery.

curl -X POST https://upload.filepost.dev/v1/upload \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@report.pdf"

You can create a free key, run that request, and open the returned URL to verify the entire upload and delivery path before choosing a paid plan.

The sections below cover the request shape, working examples in four languages, service tradeoffs, and the limits worth checking before you commit to a provider. Use the comparison table if you are evaluating tools.

What Is a File Upload API?

A file upload API is an HTTP endpoint that accepts a file in the request body and returns a URL (or identifier) for the stored file. Under the hood, the service handles:

From your app's perspective, the entire mechanism collapses into one call: POST a file, get a URL.

How a REST File Upload API Works

The standard shape of an upload request, regardless of service, is a multipart/form-data POST:

POST /v1/upload HTTP/1.1
Host: api.example.com
X-API-Key: your_api_key
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[binary file bytes]
------FormBoundary--

Most HTTP clients construct this for you: you pass a filename and the library does the boundary and encoding work. The response is typically JSON:

{
  "url": "https://cdn.example.com/uploads/a1b2c3.pdf",
  "file_id": "a1b2c3",
  "size": 245810,
  "content_type": "application/pdf"
}

The url field is the public (or signed) delivery URL. The file_id is what you store in your database so you can manage the file later.

Authentication

Most file upload APIs use one of three auth models:

For most product use cases, an API key in a header is the right default.

Code Examples

These examples use a FilePost endpoint for concreteness. Replace the URL and header with your chosen service's endpoint; the shape is the same.

cURL

curl -X POST https://upload.filepost.dev/v1/upload \
  -H "X-API-Key: your_api_key" \
  -F "file=@document.pdf"

Python (requests)

import requests

with open("document.pdf", "rb") as f:
    resp = requests.post(
        "https://upload.filepost.dev/v1/upload",
        headers={"X-API-Key": "your_api_key"},
        files={"file": f},
    )

data = resp.json()
print(data["url"])

Node.js (fetch)

import fs from "node:fs";

const form = new FormData();
form.append(
  "file",
  new Blob([fs.readFileSync("document.pdf")]),
  "document.pdf"
);

const res = await fetch("https://upload.filepost.dev/v1/upload", {
  method: "POST",
  headers: { "X-API-Key": process.env.FILEPOST_KEY },
  body: form,
});

const { url } = await res.json();
console.log(url);

Go (net/http)

package main

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func upload(path, apiKey string) (*http.Response, error) {
    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)

    f, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer f.Close()

    part, _ := writer.CreateFormFile("file", "document.pdf")
    io.Copy(part, f)
    writer.Close()

    req, _ := http.NewRequest("POST", "https://upload.filepost.dev/v1/upload", body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("X-API-Key", apiKey)

    return http.DefaultClient.Do(req)
}

Common Features Across File Upload APIs

Features that matter when you are evaluating services:

Comparison of Popular File Upload APIs

Feature FilePost Cloudinary Uploadcare UploadThing Filestack file.io
Plain REST API Yes Yes Yes No (SDK) Yes Yes
Works with any language Yes Yes Yes TS only Yes Yes
Permanent URLs Yes Yes Yes Yes Yes No (auto-delete)
Image transformations No Yes Yes No Yes No
Intake links Yes No No No No No
Free tier 50 up/mo Limited Limited Varies Trial Yes
Starting paid price 9 USD/mo 89 USD/mo 66 USD/mo 10 USD/mo 69 USD/mo Varies
Pricing model Flat Operations Credits Per-GB Credits Tiered

How to Choose a File Upload API

Use this decision tree:

File Upload API Design Considerations

If you are building (rather than buying) a file upload API, a few patterns to copy from the mature ones:

Common Pitfalls When Building on a File Upload API

Try FilePost as Your File Upload API

If you want the simplest possible REST file upload API with flat pricing, permanent URLs, and no SDK lock-in, FilePost is designed exactly for that use case. The whole API is one endpoint, works with any language that can make an HTTP request, and the free tier is enough to test a real workflow before moving production volume to a paid plan (Lite starts at $4/mo).

Try FilePost Free

One provisional 10 MB upload before verification, then 50 uploads/month and 50 MB files after verification. Full REST API access, no credit card required.

Get Your Free API Key

Summary

A file upload API is a boundary around storage, delivery, and file metadata. The right service depends on whether you need transformations, permanent URLs, a framework-specific integration, private access, or a predictable bill. FilePost is one option for the simple REST and public-URL case; the comparison above explains where that tradeoff stops fitting.

Related Posts