Dropshare Custom API

A minimal, self-hosted Dropshare Custom API server.

Features

• Drop-in Dropshare compatible: implements the exact Upload/Delete contract Dropshare's Custom API connection type expects.
• Local disk storage: files live under UPLOADS_DIR on your own server. Nothing leaves your computer.
• Single API key auth: one key in .env, checked on every upload/delete.
• Customizable link shape: serve files under /files/x.png, /s/x.png, or straight off the root (/x.png) via FILES_URL_PREFIX.
• Copy-paste-ready setup: the exact Dropshare connection settings, with your real domain and API key already filled in, are printed to the console on startup.
• Safe by default: filenames are sanitized against path traversal, uploads can't silently overwrite an existing file, and the upload directory self-heals if it's removed while the server is running.

Setup

source .venv/bin/activate
pip install -r requirements.txt
cp example.env .env

Then edit DOMAIN, API_KEY, and any other preferred settings in .env. Your API key has to be at least 16 characters long.

Run

python main.py

On startup, the exact values to paste into Dropshare such as domain, endpoints, and your real API_KEY, are printed to the console. Keep that output (and your server logs in general) private, since it includes your live API key.

Docs at /docs (Redoc), same connection settings, but with the API key redacted, since that page can be reachable over the network.

Or with Docker Compose, after the same .env setup: docker compose up -d --build.

Endpoints

Method	Path	Auth	Description
POST	/upload	Yes	Upload a file (multipart/form-data, field file)
GET	/{FILES_URL_PREFIX}/{filename}	No	Fetch an uploaded file
DELETE	/delete/{filename}	Yes	Delete a previously uploaded file

/upload and /delete are fixed management endpoints. Only the serving path (what shows up in shared links) is customizable via FILES_URL_PREFIX in .env, e.g. set it to s for dropshare.example.com/s/abc.png.

Auth: send your API_KEY as-is in the Authorization header.

Files are stored under whatever name the client uploads them with, Dropshare already generates the name per its own naming pattern in its settings, so the server doesn't second-guess it. Uploading a name that's already taken returns 409 File Already Exists rather than overwriting it.

Upload response:

{ "url": "http://domain.tld/files/photo.png", "filename": "photo.png" }

Configuring Dropshare

In Dropshare, create a new Custom API connection under Custom Services with these values (or just copy them straight from the console output on startup):

Request

Preference	Value
Upload URL	http://domain.tld/upload
Method	POST
Content-Type	multipart/form-data
Form Field	file
Header	{"Authorization": "YOUR_API_KEY"}

Response

Preference	Value
Content Type	JSON
URL to file	%url%
Delete URL	http://domain.tld/delete/%filename%
Delete Method	DELETE

YOUR_API_KEY must match API_KEY in .env.

License

Licensed under the Apache License 2.0.