Documentation

Everything you need to integrate Patrins file hosting into your applications.

Quick Start

Upload a file with a simple POST request:

curl -X POST https://patrins.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.zip" \
  -F "temporary=false"

Response:

{
  "success": true,
  "file": {
    "id": "abc123def456",
    "name": "file.zip",
    "size": "15.2 MB",
    "url": "/f/abc123def456",
    "directUrl": "/d/abc123def456"
  }
}

Authentication

All authenticated endpoints require a bearer token. Get your token by logging in:

POST /api/auth/login

{
  "email": "you@example.com",
  "password": "yourpassword"
}

The response sets an HTTP-only cookie for browser usage, or you can extract the token for API usage.

Note: Temporary file uploads don't require authentication. Anyone can upload files that auto-delete after 7 days.

Upload Files

POST /api/upload

Upload a file to your account storage.

Parameters

file (required) - The file to upload (multipart/form-data)
temporary (optional) - Set to "true" for 7-day auto-delete

Response

{
  "success": true,
  "file": {
    "id": "abc123def456",
    "name": "document.pdf",
    "size": "2.5 MB",
    "url": "/f/abc123def456",
    "directUrl": "/d/abc123def456",
    "expiresAt": "2026-03-01T12:00:00Z"  // only for temporary files
  }
}

Download Files

There are two ways to access uploaded files:

Download Page

GET /f/:id

Returns an HTML page with file info and download button. Supports custom branding for Premium users.

Direct Download

GET /d/:id

Directly downloads the file. No HTML page, just the raw file.

Manage Files

List Files

GET /api/files

Returns all files in your account.

Get File Info

GET /api/files/:id/info

Returns metadata about a specific file.

Delete File

DELETE /api/files/:id

Permanently deletes a file from your account.

Zero-Knowledge Encryption

Patrins uses client-side encryption to ensure your files remain private:

Files are encrypted in your browser before upload
Encryption keys never leave your device
We store only encrypted ciphertext
Decryption happens locally when you download

For API uploads, encryption is handled server-side. For true zero-knowledge encryption, use our browser interface or official SDK.

Temporary Files

Temporary uploads are perfect for quick sharing:

No account required
Auto-delete after 7 days
Same 50 GB file size limit
Doesn't count against storage quota

Rate Limits

To ensure fair usage, the following limits apply:

Uploads: 100 per hour
Downloads: 1000 per hour per file
API requests: 1000 per hour

Premium accounts have higher limits. Contact support for enterprise needs.