API Upload

Upload requirements

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.

Upload methods

There are several ways to add files:

  1. Upload local file over HTTP POST (see below).
  2. Upload by providing an external URL: POST /api/upload/remote
  3. Add a file that's already stored in a storage container (S3/Azure): POST /api/upload/blob
  4. Pull profile / watch folder.

HTTP Upload API workflow

The full workflow to upload files using HTTP POST is as follows:

  1. Register a new upload id using POST /api/upload/id.
  2. Upload files to the upload URL returned with the upload id, this will resolve to POST /api/file/[upload_id] .
  3. Repeat the upload step for any additional files you need to upload. If you are uploading multiple files, we recommend setting 'autofinish' to 0 in the POST /api/upload/id call.
  4. Optionally: mark the upload as finished using DELETE /api/upload/id.

Upload configuration

There are multiple config settings that can be passed to the upload/id method:

  1. max_filesize: max size in bytes for each uploaded file.
  2. max_files: max number of files that can be uploaded with this upload id.
  3. max_size: max size in bytes for all files combined.
  4. file_extensions: set a filter on accepted file extensions.
  5. no_transcode: don't transcode uploaded media.
  6. hide_response: don't return file id in upload result, it will still be in the finish call.
  7. autofinish: automatically mark the upload as finished once a file is uploaded (defaults to true, set to false for batch uploading).

Example with cURL:

curl -X POST https://example.medialab.app/upload/id \
-F "folder_id=101" \
-H "Authorization: [Bearer|Private-Token] [TOKEN_GOES_HERE]"

  "ulid": "string",
  "expires": "int",
  "expires_in": "int",
  "url_upload_direct": "string",
  "api": {
    "rel": "string",
    "upload": "string",
    "finish": "string"

curl -X POST https://upload.medialab.app/upload/file \
-F "[email protected]" \
-F "folder_id=101" \
-F "title=Video.mp4"

Upload target host

Since we utilize a hybrid cloud infrastructure, it is always necessary to register an upload first and use the provided upload URL. This is because the upload URL will point to a different domain than the tenant's API domain and may change over time. It is therefore not possible to upload a file using a single call, the upload ID is a required first step.


If you are utilizing MediaLab as API back-end for your website, you can integrate a direct upload to MediaLab from your website. If you are looking to quickly upload files from Linux servers or NAS devices, it's also possible to use simple Bash scripts. Example code can be found here on GitHub.