FileDroppr API

Authentication

Pass your key as a bearer token. Keys are scoped to your account and respect your plan's upload limits.

Authorization: Bearer fk_live_xxxxxxxx

Upload a PDF

POST /api/v1/files — multipart form, field file. Returns the file's UUID; the share link is https://filedroppr.com/<uuid>.

curl -X POST https://filedroppr.com/api/v1/files \
  -H "Authorization: Bearer fk_live_xxxxxxxx" \
  -F "[email protected]"

# {"uuid":"550e8400-…","message":"PDF uploaded successfully"}

Configure a file

PUT /api/v1/files/<uuid>/settings — JSON body. Set the viewer mode, a password, the download permission, and the expiry. Omitted fields keep their current value.

curl -X PUT https://filedroppr.com/api/v1/files/<uuid>/settings \
  -H "Authorization: Bearer fk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "viewerMode": "flipbook",
    "password": "hunter2",
    "allowDownload": false,
    "neverExpire": true
  }'

• viewerMode: standard, flipbook, swipe, or magazine.
• password: non-empty to protect (Basic+), "" to clear; allowDownload: false to disable downloads.
• requireEmail: gate viewing behind an email (Pro). notifyOnView: email you when someone opens it (Basic+).
• Expiry: "deleteAt": "<ISO 8601>" for a fixed expiry, or "neverExpire": true for a permanent link (Pro). Omit both to keep the current expiry.

Other endpoints

• GET /api/v1/files — list your files
• GET /api/v1/files/<uuid> — file details
• GET /api/v1/files/<uuid>/qr-code — QR code (PNG) for the share link
• DELETE /api/v1/files/<uuid> — delete a file
• GET /api/v1/events — recent read events across your files
• GET /api/v1/user — your account + plan

A file object (returned by list and detail) looks like:

{
  "uuid": "550e8400-…",
  "originalName": "proposal.pdf",
  "size": 91234,
  "mimeType": "application/pdf",
  "createdAt": "2026-06-15T14:00:00Z",
  "deleteAt": "2026-06-16T14:00:00Z",   // absent if it never expires
  "viewCount": 12,
  "viewerMode": "flipbook",
  "protected": true,
  "allowDownload": false,
  "requireEmail": false,
  "notifyOnView": true
}

Read events (for automations)

GET /api/v1/events returns recent reads of your files, newest first - the basis for "new read" automations (e.g. the Zapier trigger). Each event has a stable id; poll with ?since=<id> to fetch only newer ones (?limit= up to 100).

curl https://filedroppr.com/api/v1/events?since=0 \
  -H "Authorization: Bearer fk_live_xxxxxxxx"

# [{"id":42,"fileUuid":"550e8400-…","fileName":"deck.pdf",
#   "readAt":"2026-06-15T14:00:00Z","country":"United Kingdom",
#   "pagesViewed":7,"timeMs":48000}]

OAuth 2.0 (for apps)

Building an app that acts for other users? Use OAuth 2.0 (Authorization Code + PKCE) instead of asking them for an API key. Register your app with us to get a client_id (and a secret for server-side apps).

• Send users to GET /oauth/authorize with response_type=code, client_id, redirect_uri, scope, state, and a PKCE code_challenge (S256).
• After they approve, we redirect back with ?code=. Exchange it at POST /oauth/token (with code_verifier) for an access + refresh token.
• Call /api/v1 with Authorization: Bearer <access token>. Refresh with the refresh_token grant (tokens rotate); revoke at POST /oauth/revoke.
• Scopes: files:read, files:write, readership:read, profile. Users manage authorized apps under their account.

Errors

Errors come back as the HTTP status with a short plain-text message:

• 400 — bad request (e.g. the file isn't a PDF, or a malformed body)
• 401 — missing, malformed, invalid, or revoked API key
• 403 — not allowed: you don't own the file, or the setting is above your plan (e.g. password on Free)
• 404 — no such file (or not owned by you)
• 413 — the file is larger than your plan allows
• 429 — rate limit exceeded (120 requests per minute per key)

Notes

• PDF only. Max file size follows your plan (20MB free, 200MB Basic, 2GB Pro).
• Rate limit: 120 requests per minute per key.
• Revoke a key anytime from account settings — it stops working immediately.
• Readership analytics on API-uploaded files work exactly as they do in the app.