API reference

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.
The file object
{
    "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"
}

Upload a file

POST /v1/files

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=30d
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"
    }
}

List and search files

GET /v1/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"
Response
{
  "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

GET /v1/files/{id}

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"

Delete a file

DELETE /v1/files/{id}

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"
Response
{
  "deleted": true
}