Log inGet started
Features
DrivePhotosNotesCalendar and ContactsAssistantPasswordsMailFor developers
Why StavoExtensionsPricingDocsDownloadLog in
Uploaders

curl and the upload API

One request, a JSON answer. Anything that can send a multipart form can upload to your server.

1. Make an uploader on your server

  1. Sign in to your server and open Settings > Uploaders, then Add uploader.
  2. Pick curl and the API, give it a name you'll recognize, and check the folder, visibility and link style. The defaults are fine.
  3. The next page has these same steps with your server and token already filled in. The token is shown once, so copy it or download the files now.

The snippets below use https://drive.example.com and stu_YOUR_UPLOADER_TOKEN. Swap in your own if you set things up by hand.

Upload a file

bash
curl -H "Authorization: Bearer stu_YOUR_UPLOADER_TOKEN" \
  -F [email protected] \
  https://drive.example.com/api/v1/upload

POST /api/v1/upload takes multipart/form-data with the file in a field named file (if there's only one file in the form, any name works).

Optional fields

As form fields or query parameters. They override the uploader's settings for this one upload.

  • visibility: public, unlisted or private
  • link: page or direct (which one goes in url)
  • folder: a path in My Drive like Screenshots/Games (made if missing), or a folder id
  • filename, title, expires_in (seconds)

File names are cleaned (no folders, control characters or <>:"|?*) and get an extension from the type: text becomes .txt, Markdown stays .md.

The answer

201 with JSON. url follows the uploader's link style; thumbnail_url is null when there's no thumbnail. thumb_url and delete_url are the older names, kept for older tools.

json
{
  "url": "https://drive.example.com/aB3xK9q",
  "page_url": "https://drive.example.com/aB3xK9q",
  "direct_url": "https://drive.example.com/aB3xK9q.png",
  "thumbnail_url": "https://drive.example.com/aB3xK9q/thumb",
  "deletion_url": "https://drive.example.com/api/v1/uploads/aB3xK9q?token=...",
  "id": "aB3xK9q",
  "name": "screenshot.png",
  "size": 48213,
  "mime": "image/png",
  "thumb_url": "https://drive.example.com/aB3xK9q/thumb",
  "delete_url": "https://drive.example.com/api/v1/uploads/aB3xK9q?token=..."
}

Short links

With Also shorten links on, the same token can make short links. Send url as a form field, JSON or a query parameter; the short link is in url.

bash
curl -H "Authorization: Bearer stu_YOUR_UPLOADER_TOKEN" \
  -d url=https://example.com/a/very/long/link \
  https://drive.example.com/api/v1/links

Check a token

bash
curl -H "Authorization: Bearer stu_YOUR_UPLOADER_TOKEN" https://drive.example.com/api/v1/uploader

Answers with the uploader's name, folder, visibility, link style and the server's size limit.

Errors

Always JSON with an error message you can show as is.

  • 400: no file, or a field with a value it doesn't know
  • 401: no token, or a wrong, replaced or removed one
  • 403: something an uploader token can't do (anything but uploads and short links), or short links are off
  • 404: the folder id doesn't exist
  • 413: too big, with limit_bytes. Behind a Cloudflare Tunnel, 100 MB requests stop at Cloudflare first
  • 415: not a multipart form
  • 429: more than 60 requests a minute from one token. Retry-After says when to try again

Tools that can't set headers

Send the token as a token form field or ?token= on the URL instead. It works only for uploader tokens and only on the upload and short link endpoints. It's less safe: URLs end up in history and logs along the way, so prefer the header when the tool has one.

bash
curl -F token=stu_YOUR_UPLOADER_TOKEN -F [email protected] https://drive.example.com/api/v1/upload