The Drop API enables secure file sharing through a developer-friendly REST interface. All files are **encrypted client-side** using AES-256-GCM before upload, ensuring true end-to-end encryption where our servers never see your unencrypted data. ## Authentication All API requests must be authenticated using an API Key. Generate keys in your [Dashboard](/dashboard/api-keys). ```bash Authorization: Bearer ak_your_api_key_here ``` ## Base URL ``` https://anon.li/api/v1 ``` ## End-to-End Encryption

Client-Side Encryption: Unlike server-side encryption, the Drop API uses client-side E2EE. Your CLI tool or application must encrypt files locally before uploading. The encryption key is embedded in the share URL fragment and never sent to our servers.

### How It Works 1. **Generate key** - Create an AES-256-GCM key and IV locally 2. **Encrypt** - Encrypt your file and filename on your device 3. **Upload** - Send encrypted data to our API 4. **Share** - Build URL with key in fragment: `https://anon.li/d/dropId#base64Key` 5. **Download** - Recipients decrypt locally using the key from URL fragment This approach ensures: - True zero-knowledge encryption - Our servers cannot read your files - The key fragment (`#...`) is never sent to servers - Files auto-expire and are permanently deleted --- ## Endpoints ### List Drops Retrieve all your uploaded drops.

GET https://anon.li/api/v1/drop

**Query Parameters** | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `limit` | number | No | Max items to return (default: 50) | | `offset` | number | No | Pagination offset (default: 0) | **Example Request** ```bash curl https://anon.li/api/v1/drop \ -H "Authorization: Bearer ak_..." ``` **Response** ```json { "data": [ { "id": "abc123xyz", "encryptedTitle": "base64...", "iv": "base64_iv...", "downloads": 3, "maxDownloads": 10, "expires_at": "2026-01-15T00:00:00.000Z", "created_at": "2026-01-08T12:00:00.000Z", "fileCount": 2, "totalSize": "1048576" } ], "total": 1, "storage": { "used": "5242880", "limit": "1073741824" } } ``` --- ### Create Drop Create a new drop container for uploading encrypted files.

POST https://anon.li/api/v1/drop

**Body Parameters** | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `iv` | string | Yes | Base64-encoded initialization vector (12 bytes) | | `encryptedTitle` | string | No | Encrypted title (base64) | | `encryptedMessage` | string | No | Encrypted message (base64) | | `fileCount` | number | Yes | Number of files to upload | | `expiry` | number | No | Days until expiration | | `maxDownloads` | number | No | Max download count | **Example Request** ```bash curl -X POST https://anon.li/api/v1/drop \ -H "Authorization: Bearer ak_..." \ -H "Content-Type: application/json" \ -d '{ "iv": "base64_iv_here", "fileCount": 1, "expiry": 7, "maxDownloads": 10 }' ``` **Response** ```json { "dropId": "abc123xyz", "sessionToken": null, "expiresAt": "2026-01-15T00:00:00.000Z" } ``` --- ### Add File to Drop Add an encrypted file to an existing drop.

POST https://anon.li/api/v1/drop/:id/file

**Body Parameters** | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `size` | number | Yes | File size in bytes | | `encryptedName` | string | Yes | Encrypted filename (base64) | | `iv` | string | Yes | File IV (base64, 12 bytes) | | `mimeType` | string | Yes | MIME type | | `chunkCount` | number | Yes | Number of chunks | | `chunkSize` | number | Yes | Size per chunk | **Response** ```json { "fileId": "file123", "s3UploadId": "upload-id", "uploadUrls": [ "https://presigned-url-for-chunk-1...", "https://presigned-url-for-chunk-2..." ] } ``` --- ### Get Drop Get drop metadata and files for download.

GET https://anon.li/api/v1/drop/:id

**Response** ```json { "id": "abc123xyz", "encryptedTitle": "base64...", "encryptedMessage": "base64...", "iv": "base64_iv...", "passwordProtected": false, "downloads": 4, "maxDownloads": 10, "expiresAt": "2026-01-15T00:00:00.000Z", "files": [ { "id": "file123", "encryptedName": "base64...", "size": "1048576", "mimeType": "application/pdf", "iv": "base64...", "downloadUrl": "https://presigned-url..." } ] } ``` --- ### Delete Drop Delete a drop you own.

DELETE https://anon.li/api/v1/drop/:id

**Response** ```json { "success": true } ``` --- ## CLI Upload Workflow For CLI tools, implement the following workflow: ```javascript import crypto from 'crypto'; // 1. Generate encryption key and IV const key = crypto.randomBytes(32); // 256-bit key const iv = crypto.randomBytes(12); // 96-bit IV for AES-GCM // 2. Encrypt file const cipher = crypto.createCipheriv('aes-256-gcm', key, iv); const encrypted = Buffer.concat([cipher.update(fileBuffer), cipher.final()]); const authTag = cipher.getAuthTag(); const encryptedData = Buffer.concat([encrypted, authTag]); // 3. Encrypt filename const nameCipher = crypto.createCipheriv('aes-256-gcm', key, iv); const encryptedName = Buffer.concat([ nameCipher.update(filename, 'utf8'), nameCipher.final(), nameCipher.getAuthTag() ]).toString('base64'); // 4. Create drop const drop = await fetch('https://anon.li/api/v1/drop', { method: 'POST', headers: { 'Authorization': 'Bearer ak_...', 'Content-Type': 'application/json' }, body: JSON.stringify({ iv: iv.toString('base64'), fileCount: 1, expiry: 7 }) }).then(r => r.json()); // 5. Add file and get presigned URLs const file = await fetch(`https://anon.li/api/v1/drop/${drop.dropId}/file`, { method: 'POST', headers: { 'Authorization': 'Bearer ak_...', 'Content-Type': 'application/json' }, body: JSON.stringify({ size: encryptedData.length, encryptedName, iv: iv.toString('base64'), mimeType: 'application/octet-stream', chunkCount: 1, chunkSize: encryptedData.length }) }).then(r => r.json()); // 6. Upload encrypted data to presigned URL await fetch(file.uploadUrls[0], { method: 'PUT', body: encryptedData }); // 7. Complete the drop (marks it ready for download) await fetch(`https://anon.li/api/v1/drop/${drop.dropId}/complete`, { method: 'POST', headers: { 'Authorization': 'Bearer ak_...' } }); // 8. Build share URL with key in fragment const shareUrl = `https://anon.li/d/${drop.dropId}#${key.toString('base64url')}`; console.log('Share URL:', shareUrl); ``` ## Error Responses | Status | Description | | :--- | :--- | | `400` | Bad Request - Missing required fields or invalid parameters | | `401` | Unauthorized - Invalid or missing API key | | `403` | Forbidden - Feature not available on your plan | | `404` | Not Found - Drop doesn't exist | | `410` | Gone - Drop expired or download limit reached | | `429` | Too Many Requests - Rate limit exceeded | | `500` | Internal Server Error | ## Rate Limits | Operation | Limit | | :--- | :--- | | Drop creation | 30 requests/hour | | Drop list | 60 requests/minute | | Drop delete | 60 requests/hour | ## Plan Limits | Feature | Free | Plus | Pro | | :--- | :--- | :--- | :--- | | Bandwidth | 5 GB | 50 GB | 250 GB | | Max file size | 5 GB | 50 GB | 250 GB | | Max expiry | 3 days | 7 days | 30 days | ## Security Notes - **Client-side encryption** - Files are encrypted on your device before upload - **Zero-knowledge** - We never see your unencrypted data or encryption keys - **URL fragments are private** - The `#key` part of share URLs is never sent to servers - **AES-256-GCM** - Authenticated encryption with 256-bit keys - **Files auto-expire** - All files are automatically deleted after their expiry date