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 start the Windows or Mac OS 4file app installer from the secure link flow. Linux and mobile devices should receive an unsupported-platform error.

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 file download is blocked; the secure link detects the OS and starts the matching Windows or Mac OS app installer.

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 Windows/Mac app delivery for protected files? Use delivery policies and one-time tokens.

Create account Get Desktop App