file.io API Guide: cURL, Endpoints, Expiration, Limits (2026)

file.io is one of the simplest file-transfer APIs on the internet. Upload a file with a single cURL command, get back a shareable URL, and the file auto-deletes after download (or after a retention window). For one-off transfers between developers, or for scripts that need to hand a file to someone without setting up S3, it is hard to beat.

The official documentation is thin. This guide covers every piece you actually need: the endpoint, the cURL command, expiration rules, size limits, rate limits, and what to do when file.io's auto-delete default is the wrong fit for your use case.

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

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 cURL-first ergonomics (POST a file, get a URL), but the URL 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, no surprise-when-it-disappears.

Quick Comparison: file.io vs FilePost

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.