What is the file.io API endpoint?

The file.io upload endpoint is https://file.io. You POST a multipart form-data request with the file attached, and the response is a JSON body with a shareable URL, a key, and an expiration timestamp.

What is the default expiration on file.io?

file.io's default is to delete the file after the first successful download (one-time link). If you set an expires parameter, the file is deleted after that duration instead (for example, 1d, 7d, 14d). The historical 14-day default was the maximum retention before the file would auto-delete even without being downloaded. Free-tier files currently expire after a single download unless you pass an explicit expires value.

What is the file size limit on file.io?

The free tier caps uploads at 100 MB per file. Paid plans increase this up to 5 GB per file. If your use case requires files between 100 MB and 500 MB without a paid plan, an alternative service like FilePost offers 50 MB on free and 500 MB on the 9 USD paid tier.

How do I upload a file to file.io with cURL?

Use: curl -F 'file=@yourfile.pdf' https://file.io. The response is JSON containing a link field with the shareable URL. Add parameters like expires=1w to change retention, or autoDelete=false (on paid plans) to disable auto-delete after download.

Can I use file.io for permanent file hosting?

No. file.io is designed for ephemeral transfers. Even with the longest retention setting, files are not meant to be permanent. If you need permanent public URLs (for apps, automation, email attachments, or CDN delivery), use a service like FilePost that keeps files until you delete them.

file.io API Guide: cURL Uploads, Expiry Rules, and Permanent URL Fix

April 19, 2026 · Updated May 13, 2026 · 8 min read

file.io is a tiny upload API with a very developer-friendly shape: send one multipart/form-data request, get JSON back, copy the link field. For a debug log, a one-off build artifact, or a quick file handoff, that is exactly the right amount of API.

The catch is durability. On the free tier, file.io is built around expiring files and one-download links. This guide covers the upload endpoint, the cURL command, the file form field, maxDownloads, expiry rules, size limits, and the practical fix when your app needs a URL that stays online.

Developer summary

Upload endpoint: POST https://file.io
Request body: multipart/form-data with the file attached as file
Response: JSON with a link, key, expiry fields, download count, and size metadata
Default behavior: free uploads are meant for temporary sharing, often one download via maxDownloads: 1 and autoDelete: true
Use FilePost instead when: the returned URL needs to be a permanent CDN URL, listed later, deleted by API, or used inside production automation

file.io API Endpoint

file.io uses a single endpoint for uploads:

POST https://file.io

The body is a multipart/form-data request with the file attached under the file field. There is no API key required for the free tier, and no separate "auth" call; the upload IS the whole flow.

Upload a File with cURL

The canonical one-line cURL upload:

curl -F "file=@report.pdf" https://file.io

Response (JSON):

{
  "success": true,
  "status": 200,
  "id": "abc123xyz",
  "key": "abc123xyz",
  "link": "https://file.io/abc123xyz",
  "expiry": "14 days",
  "expires": "2026-05-03T14:30:00.000Z",
  "downloads": 0,
  "maxDownloads": 1,
  "autoDelete": true,
  "size": 245810,
  "mimeType": "application/pdf",
  "created": "2026-04-19T14:30:00.000Z",
  "modified": "2026-04-19T14:30:00.000Z"
}

The link field is the shareable URL. Send that to whoever needs the file, and they can download it from a browser or another cURL.

Upload with a Custom Expiration

Add an expires form field to override the default:

curl -F "file=@report.pdf" -F "expires=1d" https://file.io

Accepted values:

1y, 2y, 3y (years, paid plan required for longer periods)
1w, 2w (weeks)
1d, 7d, 14d (days)
1h, 6h, 24h (hours, paid plan)

Retention longer than 14 days typically requires a paid plan.

Upload with autoDelete Disabled (Paid)

On paid plans, you can keep the file available after the first download:

curl -F "file=@report.pdf" \
     -F "autoDelete=false" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     https://file.io

On the free tier, autoDelete is always true and cannot be disabled.

Default Expiration Rules

This is where most confusion lives. file.io has two independent expiration mechanisms, and both apply:

1. Auto-delete after first download

Every file.io free-tier upload defaults to maxDownloads: 1 and autoDelete: true. The moment someone downloads the file, it is gone. This is the behavior most developers remember and what makes file.io ideal for one-time transfers.

2. Time-based expiration

Even if nobody downloads the file, it still expires after a fixed retention period. The historical default was 14 days. Current defaults may vary; check the expires field in the response to see exactly when your specific upload will vanish.

Whichever happens first, wins. If someone downloads the file on day 3 it is deleted immediately. If nobody downloads it, it is deleted at the end of the retention window.

File Size Limits

Plan	Max File Size	Monthly Upload Allowance
Free	Around 100 MB	Rate-limited
Basic (paid)	Up to 1 GB	Larger allowance
Premium (paid)	Up to 5 GB	Largest allowance

Exact numbers change over time; check the file.io pricing page for the current caps. If your real need is files between 100 MB and 500 MB without paying, see the alternatives section below.

Rate Limits

file.io rate-limits anonymous IPs. If you hit 429 responses from a server running automated uploads, you are past the free-tier ceiling. Options:

Upgrade to a paid plan, which raises the limit per authenticated key.
Spread uploads across multiple IPs (not recommended).
Switch to a service with predictable plan-based rate limits, like FilePost (10 req/second on free, 50 on Starter, 200 on Pro).

Downloading and Inspecting Files

Every upload response includes a link. Anyone with that URL can download the file:

curl -OJ https://file.io/abc123xyz

-O tells cURL to save the file; -J uses the server-provided filename if present.

file.io does not provide a list-my-files or metadata-lookup endpoint on the free tier. Once you upload, you only know about the file through the response you captured. If you lose the response, you lose the file. Paid plans add account-level file management.

When file.io Is the Right Choice

file.io is a great fit when:

You need a one-time share link (think: sending a debug log to a colleague).
The file is small (< 100 MB).
You explicitly want the file to disappear after download.
You do not need a file management UI or API.
You do not need the URL to stay stable in production systems.

When file.io Is the Wrong Choice

file.io does not fit when:

You need a URL that stays live in production (apps, emails, automation workflows).
You want to list, inspect, or selectively delete files later.
You need file-upload ingress at scale with predictable rate limits.
You want a paid plan but prefer flat pricing over tier-gated feature locks.
Your files are over 100 MB and you do not want to upgrade just for size.

For those cases, a persistent upload API is the better shape. FilePost keeps the same developer flow, POST a file and get a URL, but the returned URL is a permanent CDN URL that stays up until you delete it.

FilePost cURL Upload Example

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

Response:

{
  "url": "https://cdn.filepost.dev/file/filepost/uploads/a1/a1b2c3.pdf",
  "file_id": "a1b2c3d4e5f6",
  "size": 245810
}

The response url is a permanent CDN-backed URL. No expiration, no auto-delete, and no "this worked yesterday" debugging session when a workflow tries to reuse the link.

Try FilePost Free

300 uploads per month, 50MB max file size on free, 500MB on 9 USD paid. Full REST API.

Get Your Free API Key

Quick Comparison: file.io vs FilePost

Feature	file.io	FilePost
cURL one-liner upload	Yes	Yes
Permanent URLs	No (auto-delete default)	Yes
File management API (list/delete)	Paid only	Yes (free)
Max file size (free)	Around 100 MB	50 MB
Max file size (starter paid)	1 GB	500 MB
Free tier monthly uploads	Rate-limited	300/mo
Starting paid price	Varies by plan	9 USD/mo (5,000 uploads)
Best fit	One-time transfers	Production file hosting

Common file.io Error Codes

400 Bad Request: Missing the file form field, or the file body is empty.
413 Payload Too Large: File exceeds the free or paid size cap. Check the size caps in the table above.
429 Too Many Requests: Rate limit hit. Wait, slow down, or upgrade.
500 Internal Server Error: Transient server issue; retry with backoff.

Summary

file.io does exactly one thing and does it well: ephemeral file transfers with a minimal cURL interface. The default is aggressive auto-delete after the first download, which is perfect for one-time sharing and the wrong choice for anything that needs a stable URL.

If you need the cURL ergonomics of file.io plus permanent URLs, a management API, and predictable pricing, FilePost is the closest adjacent tool. Same muscle memory, different durability.

Get your free API key

You're in!