API reference

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.

Start a large upload

POST /v1/uploads/direct

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:

  1. Ask for an upload here.
  2. PUT the file to upload_url within 15 minutes, with every header listed in headers.
  3. 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
Response
{
    "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

POST /v1/uploads/direct/{id}/complete

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"
Response
{
    "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": "![q3-revenue](https://cdn.drop.media/acme/q3-revenue.png)",
        "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"
    }
}