API Upload

Single file

To upload a file to our API, you must meet the following criteria:

  1. The user must have level "Uploader" or higher.
  2. You need to request the 'upload' scope when using OAuth2, or use a private token.

A file can be uploaded using a single POST call to the /api/upload/file endpoint. You will need to provide a valid target folder as parameter, and optionally a custom title for the file.

Example with cURL:

curl -X POST https://example.medialab.co/upload/file \
-F "file=@MyFile.txt" \
-F "folder_id=101" \
-F "title=Video.mp4" \
-H "Authorization: [Bearer|Private-Token] [TOKEN_GOES_HERE]" \

Multiple files

If you are uploading multiple files, we recommend a slightly different workflow by first registering a new upload id. The files can then be uploaded the usual way but by providing the upload id for each file, you let us know these files belong together. During the upload process, the upload will be visible in the "Active uploads" tab in our Workflow Manager for administrators. When all files have been uploaded, you can mark the upload id as finished, at which point we will trigger one event to inform the online users of the upload.

Reasons to upload in a batch vs single files:

  1. Online users will be able to see the active upload in their Workflow Manager.
  2. One event will be triggered to inform users of the upload instead of one event per single file.
  3. It will be easier to implement new features for batch uploads, such as adding metadata or target folder.

The workflow to upload in a batch:

  1. Register a new upload id using POST /api/upload/id.
  2. Upload files to POST /api/upload/file/[upload_id] while providing your registered upload id.
  3. Mark the upload as finished using DELETE /api/upload/id.