4file API

Programmatic access to uploads, links, and file delivery policies. This is a fictional demo API for api.4file.org — you can adapt it to your backend easily.

Base URL: https://api.4file.org/v1 Auth: Bearer API Key JSON Rate Limits

Quick Start

Authentication

Use an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep keys secret. Rotate immediately if leaked.

Standard Response

All responses are JSON. Errors follow a consistent shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_9f2a..."
  }
}

Rate Limits

Requests are rate-limited per API key. Limits can vary by plan. The API returns rate limit headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1734950400

Objects

File

{
  "id": "file_2m3YkQ",
  "name": "build.zip",
  "size": 73400320,
  "sha256": "f3b2...9a1c",
  "created_at": "2025-12-23T10:18:11Z",
  "expires_at": "2026-01-23T00:00:00Z",
  "downloads_left": 3,
  "delivery_policy": "web_or_desktop"
}

Link

{
  "id": "lnk_k81wQ1",
  "url": "https://4file.org/dl?token=ABCD1234",
  "password_protected": false,
  "expires_at": null,
  "max_downloads": null,
  "delivery_policy": "desktop_only"
}

Upload Flow

Recommended flow for large files: create an upload session → upload parts → finalize → generate link.

POST

/uploads

Create an upload session (multipart or single-shot).

Field	Type	Description
name	string	Original file name
size	integer	Bytes
sha256	string	Optional integrity hash
expires_at	string	ISO timestamp or null
max_downloads	integer	Optional limit
delivery_policy	string	web_or_desktop \| desktop_only

curl -X POST https://api.4file.org/v1/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "build.zip",
    "size": 73400320,
    "sha256": "f3b2...9a1c",
    "expires_at": "2026-01-23T00:00:00Z",
    "max_downloads": 3,
    "delivery_policy": "desktop_only"
  }'

{
  "upload_id": "upl_7yN1cD",
  "part_size": 5242880,
  "upload_url": "https://upload.4file.org/u/upl_7yN1cD",
  "expires_in": 3600
}

PUT

/uploads/{upload_id}/parts/{part_number}

Upload a binary part. Provide Content-Range and optional part hash.

curl -X PUT "https://api.4file.org/v1/uploads/upl_7yN1cD/parts/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Range: bytes 0-5242879/73400320" \
  --data-binary @part1.bin

{
  "part_number": 1,
  "etag": "etag_3f9c...",
  "received": 5242880
}

POST

/uploads/{upload_id}/finalize

Finalize upload and create a file object.

curl -X POST "https://api.4file.org/v1/uploads/upl_7yN1cD/finalize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {"part_number": 1, "etag": "etag_3f9c..."}
    ]
  }'

{
  "file": {
    "id": "file_2m3YkQ",
    "name": "build.zip",
    "size": 73400320,
    "delivery_policy": "desktop_only",
    "created_at": "2025-12-23T10:18:11Z"
  }
}

Links & Sharing

POST

/files/{file_id}/links

Create a share link for an existing file.

Field	Type	Description
password	string	Optional password (stored hashed)
expires_at	string	Optional ISO timestamp
max_downloads	integer	Optional download limit
delivery_policy	string	web_or_desktop \| desktop_only

curl -X POST "https://api.4file.org/v1/files/file_2m3YkQ/links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-01-23T00:00:00Z",
    "max_downloads": 3,
    "delivery_policy": "desktop_only"
  }'

{
  "link": {
    "id": "lnk_k81wQ1",
    "url": "https://4file.org/dl?token=ABCD1234",
    "delivery_policy": "desktop_only"
  }
}

GET

/links/{link_id}

Get link details (without exposing secrets).

curl -X GET "https://api.4file.org/v1/links/lnk_k81wQ1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Downloads & Delivery Policies

4file supports delivery enforcement. If a link is configured as desktop_only, web download attempts should be redirected to the Desktop App flow (like your secure modal).

POST

/links/{link_id}/tokens

Issue a one-time download token (used by Desktop App to fetch via a protected channel).

curl -X POST "https://api.4file.org/v1/links/lnk_k81wQ1/tokens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"download"}'

{
  "token": "9B3F2C1A...E7D1",
  "expires_in": 120,
  "delivery_policy": "desktop_only"
}

Delivery Policy Values

web_or_desktop — normal link, allowed via browser or Desktop App.

desktop_only — browser download is blocked; token-based delivery through Desktop App only.

List & Manage Files

GET

/files

List files for the authenticated account (paginated).

curl -X GET "https://api.4file.org/v1/files?limit=20&cursor=next_abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"id":"file_2m3YkQ","name":"build.zip","size":73400320,"created_at":"2025-12-23T10:18:11Z"}
  ],
  "next_cursor": "next_def"
}

DELETE

/files/{file_id}

Delete a file and revoke its links.

curl -X DELETE "https://api.4file.org/v1/files/file_2m3YkQ" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "deleted": true }

HTTP Status Codes

Code	Meaning
200	OK
201	Created
400	Invalid request
401	Unauthorized (missing/invalid API key)
403	Forbidden (policy or permissions)
404	Not found
409	Conflict (state mismatch)
429	Rate limited
500	Server error

Build with 4file

Want the Desktop App flow for protected files? Use delivery policies and one-time tokens.

Create account Get Desktop App