API reference

Overview

A JSON API over HTTPS for uploading, finding and sharing files from your own code.

Base URL

https://drop.media/api/v1

Authentication

Send an API key as a bearer token on every request. Each endpoint needs an ability, listed with it.

$ curl https://drop.media/api/v1/me -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

POST /files Upload a file files:write
GET /files List and search files files:read
GET /files/{id} Get a file files:read
POST /files/{id}/link Make a share link files:read
DELETE /files/{id} Delete a file files:delete
POST /uploads Make a one-time upload URL files:write
POST /uploads/direct Start a large upload files:write
POST /uploads/direct/{id}/complete Finish a large upload files:write
GET /me The account, its limits and the key any

Requests

  • Send parameters as JSON (Content-Type: application/json), form fields, or multipart form data. Uploading a file's bytes needs multipart.
  • Send Accept: application/json; responses are always JSON.
  • Successful responses wrap the result in data.

Errors

Errors have a message written for people, and validation errors add errors by field:

{
    "message": "Expiry can be at most 365 days away.",
    "errors": {
        "file": [
            "Expiry can be at most 365 days away."
        ]
    }
}
401No API key, or it's wrong or revoked.
402The account can't use the API yet: on the free plan, verify the email address first.
403The key doesn't have the ability this endpoint needs.
404No such file in this account.
409An upload URL is already receiving a file, or was used for a different one.
422The request or the file was refused: an unsupported type, too big, over the plan's limits, a bad option. The message says which.
429Too many requests. Wait and try again.

Rate limits

Each account can make 120 requests a minute across the API and the MCP server. Past that, requests get 429 with a Retry-After header saying how many seconds to wait.

Pagination

GET /files takes page and per_page (up to 100) and returns meta with page, per_page, total and has_more. Keep asking for the next page while has_more is true.

Logs

Every request a key makes is in Logs for 30 days, with the request and response bodies (secrets removed). It's the first place to look when a call doesn't do what you expected.