REST File Upload API: Working Examples and a Public URL

· · 10 min read

The shortest working pattern is one multipart POST: send a form field named file to https://upload.filepost.dev/v1/upload with your API key in X-API-Key. The JSON response contains a public CDN URL in url.

FilePost files have no automatic expiry by default. The first upload on a free account before email verification is provisional and expires after 24 hours unless the account verifies; any requested expiry also applies.

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.

This guide covers what a file upload API actually does, the REST shape of a typical upload request, working code in four languages, the tradeoffs between services, and how to choose the one that fits your stack. If you are evaluating tools, skip to the comparison table and the how-to-choose section.

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 15 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 thin abstraction over object storage, CDN, and metadata that turns "handle file uploads in my app" into a single HTTP call. The right service depends on whether you need transformations, permanence, a specific framework integration, or a flat price. For most developers shipping a product, the "simple REST, any language, permanent URLs, flat pricing" profile is the right starting point, and that is what FilePost is built for.

Related Posts