Uploads
Two ways to upload without sending the bytes through POST /files: one-time upload URLs, for anything that shouldn't hold a key, and direct uploads, for files up to 5 GB.
Make a one-time upload URL
Returns a URL that accepts one file with a plain PUT, no key needed, for 15 minutes. Use it to let a sandboxed agent, a browser or a device upload without giving it a key. It's what the MCP tool create_upload_link uses. Needs files:write.
| filenamerequiredstring | The name of the file that will be sent, e.g. screenshot.png. |
| visibility, expires_in, name, prompt, model | As for uploading a file. They're checked now, so mistakes show up before the upload. |
Sending the file
PUT the raw bytes to upload_url. It returns 201 with the file. If the connection drops, sending the same file again returns the file already stored (200) instead of a copy. A different file gets 409.
Checking on it
GET the same URL to see whether the upload finished: status is pending, then completed with the file.
$ curl https://drop.media/api/v1/uploads -H "Authorization: Bearer YOUR_API_KEY" \
-d filename=screenshot.png -d expires_in=30d{
"data": {
"upload_url": "https://drop.media/api/v1/uploads/Xq3\u202648 characters\u20269Zt",
"method": "PUT",
"status_url": "https://drop.media/api/v1/uploads/Xq3\u202648 characters\u20269Zt",
"max_bytes": 104857600,
"expires_at": "2026-11-18T09:45:00+00:00",
"curl": "curl --fail-with-body -T 'screenshot.png' 'https://drop.media/api/v1/uploads/Xq3\u202648 characters\u20269Zt'"
}
}$ curl --fail-with-body -T screenshot.png "UPLOAD_URL"Start a large upload
For big files: the bytes go straight to storage, so they can be as large as the plan allows (5 GB on Pro). Three steps:
- Ask for an upload here.
PUTthe file toupload_urlwithin 15 minutes, with every header listed inheaders.- Complete it, which checks the file and adds it to the library.
The response includes both commands, ready to run, in curl. Needs files:write.
| filenamerequiredstring | The name of the file, e.g. demo.mp4. |
| sizeinteger | Its size in bytes, so a file that's too big is refused now rather than after uploading. |
| visibility, expires_in, name, prompt, model | As for uploading a file. |
$ curl https://drop.media/api/v1/uploads/direct -H "Authorization: Bearer YOUR_API_KEY" \
-d filename=demo.mp4 -d size=734003200{
"data": {
"id": "9b2f6c1e-3a4d-4e8b-a7c5-1d0e2f3a4b5c",
"upload_url": "https://\u2026s3.amazonaws.com/\u2026?X-Amz-Signature=\u2026",
"method": "PUT",
"headers": {
"Content-Type": "video/mp4"
},
"max_bytes": 5368709120,
"expires_at": "2026-11-18T09:45:00+00:00",
"complete_url": "https://drop.media/api/v1/uploads/direct/9b2f6c1e-3a4d-4e8b-a7c5-1d0e2f3a4b5c/complete",
"curl": {
"upload": "curl --fail-with-body -T 'demo.mp4' -H 'Content-Type: video/mp4' 'https://\u2026'",
"complete": "curl --fail-with-body -X POST -H 'Authorization: Bearer $DROP_API_KEY' '\u2026/complete'"
}
}
}Finish a large upload
Call it after the PUT has finished. The file is checked like any upload and added to the library: 201 with the file. Completing again returns the same file with 200, so it's safe to retry.
An upload that hasn't been completed within 23 hours is discarded. Needs files:write.
$ curl -X POST https://drop.media/api/v1/uploads/direct/UPLOAD_ID/complete -H "Authorization: Bearer YOUR_API_KEY"{
"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"
}
}