Files
Upload, list, get, share and delete files.
The file object
| idstring | The file's id: a UUID, or the name you gave it. Also the last part of its link. |
| urlstring | Public files: a permanent CDN link. Private files: a signed link that expires at url_expires_at. |
| url_expires_attimestamp | null | When url stops working. Null for public files. |
| thumbnail_urlstring | null | A small preview, for images, PDFs and videos. |
| markdownstring | An image or link snippet with url, ready to paste. |
| namestring | The original file name. |
| mime_typestring | The type, checked from the contents. |
| sizeinteger | Bytes. |
| width, heightinteger | null | For images. |
| visibilitystring | public or private. |
| expires_attimestamp | null | When the file will be deleted, if ever. |
| sourcestring | How it came in: web, api, mcp, email or sftp. |
| prompt, modelstring | null | For AI-made images, the prompt and model, if they were given. |
| created_attimestamp | When it was added. |
{
"id": "q3-revenue",
"url": "https://cdn.drop.media/acme/q3-revenue.png",
"url_expires_at": null,
"thumbnail_url": "https://cdn.drop.media/acme/thumbnail/q3-revenue.png",
"markdown": "",
"name": "q3-revenue.png",
"mime_type": "image/png",
"size": 48213,
"width": 1600,
"height": 900,
"visibility": "public",
"expires_at": "2026-12-18T09:30:00+00:00",
"source": "api",
"prompt": null,
"model": null,
"created_at": "2026-11-18T09:30:00+00:00"
}Upload a file
Send the file one of three ways: as multipart file, as content_base64 with a filename, or as a url to fetch. Needs files:write.
For files bigger than about 100 MB, or when the uploader shouldn't hold a key, use Uploads.
| filefile | The file, as multipart form data. |
| content_base64string | The contents, base64 encoded (a data: URI also works). Needs filename. |
| filenamestring | The name including extension, e.g. chart.png. |
| urlstring | A public http(s) URL to fetch the file from. |
| visibilitystring | public (default) or private. |
| expires_induration | Delete the file after this long: 30m, 12h, 7d, 2w, or an ISO 8601 date. |
| namestring | A readable id for the link instead of a UUID: letters, numbers, - and _, up to 100. |
| promptstring | For an AI-made image, the prompt. It's kept with the file and searchable. |
| modelstring | For an AI-made image, the model. |
Returns 201 with the file.
$ curl https://drop.media/api/v1/files \
-H "Authorization: Bearer YOUR_API_KEY" \
-F file=@chart.png \
-F name=q3-revenue -F expires_in=30dconst form = new FormData();
form.append('file', new Blob([await fs.readFile('chart.png')]), 'chart.png');
form.append('name', 'q3-revenue');
form.append('expires_in', '30d');
const res = await fetch('https://drop.media/api/v1/files', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.DROP_API_KEY}` },
body: form,
});
const { data } = await res.json();res = requests.post(
'https://drop.media/api/v1/files',
headers={'Authorization': f"Bearer {os.environ['DROP_API_KEY']}"},
files={'file': open('chart.png', 'rb')},
data={'name': 'q3-revenue', 'expires_in': '30d'},
)
file = res.json()['data']$ curl https://drop.media/api/v1/files \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/chart.png", "visibility": "private"}'{
"data": {
"id": "q3-revenue",
"url": "https://cdn.drop.media/acme/q3-revenue.png",
"url_expires_at": null,
"thumbnail_url": "https://cdn.drop.media/acme/thumbnail/q3-revenue.png",
"markdown": "",
"name": "q3-revenue.png",
"mime_type": "image/png",
"size": 48213,
"width": 1600,
"height": 900,
"visibility": "public",
"expires_at": "2026-12-18T09:30:00+00:00",
"source": "api",
"prompt": null,
"model": null,
"created_at": "2026-11-18T09:30:00+00:00"
}
}List and search files
Newest first. Expired files aren't included. Needs files:read.
| searchstring | Words to find in names and AI prompts. Every word must match. |
| typestring | images, video, audio, pdfs, docs (text, JSON and Office files) or generated. |
| per_pageinteger | 1 to 100. Default 20. |
| pageinteger | Starting at 1. |
$ curl "https://drop.media/api/v1/files?search=revenue&type=images" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": [
{ "id": "q3-revenue", "url": "https://cdn.drop.media/acme/q3-revenue.png", … }
],
"meta": {
"page": 1,
"per_page": 20,
"total": 1,
"has_more": false
}
}Get a file
For a private file, url is a fresh signed link that works for an hour. Needs files:read.
$ curl https://drop.media/api/v1/files/q3-revenue -H "Authorization: Bearer YOUR_API_KEY"Make a share link
Returns the file with a link to hand out. For a private file it's a signed link that lasts ttl; for a public file it's the permanent link. Sends a file.shared webhook. Needs files:read.
| ttlduration | How long a private file's link works: 15m, 1h, 3d. Default 1 hour, at most 7 days. |
$ curl -X POST https://drop.media/api/v1/files/FILE_ID/link \
-H "Authorization: Bearer YOUR_API_KEY" -d ttl=3d{
"data": {
"id": "7c1e4b2a-5d3f-4a8e-b6c9-0f2d8e4a1b37",
"url": "https://drop.media/p/7c1e4b2a-5d3f-4a8e-b6c9-0f2d8e4a1b37?ref=4821&expires=1795521600&signature=8f3c\u2026",
"url_expires_at": "2026-11-19T10:30:00+00:00",
"thumbnail_url": "https://drop.media/p/7c1e4b2a-5d3f-4a8e-b6c9-0f2d8e4a1b37?ref=4821&expires=1795521600&signature=8f3c\u2026&thumbnail=1",
"markdown": "[contract-draft.pdf](https://drop.media/p/7c1e4b2a-5d3f-4a8e-b6c9-0f2d8e4a1b37?ref=4821&expires=1795521600&signature=8f3c\u2026)",
"name": "contract-draft.pdf",
"mime_type": "application/pdf",
"size": 284113,
"width": null,
"height": null,
"visibility": "private",
"expires_at": null,
"source": "api",
"prompt": null,
"model": null,
"created_at": "2026-11-18T09:30:00+00:00"
}
}Delete a file
Deletes the file and its links straight away. Sends a file.deleted webhook. Needs files:delete.
$ curl -X DELETE https://drop.media/api/v1/files/q3-revenue -H "Authorization: Bearer YOUR_API_KEY"{
"deleted": true
}