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.
  4. 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. no_transcode: don't transcode uploaded media.
  5. hide_response: don't return file id in upload result, it will still be in the finish call.
  6. file_extensions: set a filter on accepted file extensions.

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 "file=@MyFile.txt" \
-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.

Example: Public Upload Form

If you are utilizing MediaLab as API back-end for your website, you can integrate a direct upload to MediaLab from your website. Example code for this set-up is available here on GitHub.

Example: Bash Upload

It is also possible to upload files using cURL from a Bash script. An example can be found in our API toolbox available here on GitHub.