Home

    General

      API Methods

        Authentication

        Upload

        Webhooks

        oEmbed

        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.

        Supported methods

        We strive to support a variety of methods to upload files to MediaLab to ensure each use case can pick their best option. The following methods are currently supported:

        1. TUS resumable uploads protocol (tus.io)
        2. Upload file using HTTP POST. - POST /api/upload/file
        3. Upload by providing an external URL - POST /api/upload/remote
        4. Add a file that's already stored in a storage container (S3/Azure): - POST /api/upload/blob
        5. Upload directly to S3 bucket
        6. MediaLab Connect desktop application - Get MediaLab Connect
        7. Pull profile / watch folder - configure this through the interface
        8. FTP upload - configure this through the interface

        TUS resumable uploads protocol

        TUS resumable uploads protocol is a standardized way to upload files to a server. It allows you to upload files in chunks and resume the upload later. The protocol is described here and has plenty of open source clients available to implement. The full workflow to upload files using TUS is as follows:

        1. Register a new upload id using POST /api/upload/id.
        2. The upload id contains information about our TUS API: the API location and an authorization header that must be included in any requests made to the TUS API.
        3. Register each file by executing a POST to the TUS API returned with the upload id, this will return the location of the file.
        4. Start a PATCH request to upload the new file as outlined in the TUS protocol. Any metadata can be added in line with the TUS protocol.
        5. Mark the upload as finished using DELETE /api/upload/id.

        POST Uploads

        The API supports regular form-based POST uploads. This can be used to upload a file from a script or let users upload directly with a file input / uploader from your own website.

        This upload flow only requires your API authorization to register a new upload and to mark it as finished afterwards. The file uploads will be executed to a signed URL returned from our API when registering the upload id.

        If you are planning to let your users upload to our API directly without exposing your API credentials, please ensure to set the "hide_response" flag to indicate the uploader should not receive any confidential information.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 signed upload URL returned with the upload id, this will resolve to POST /api/file/[upload_id].Do NOT include any additional authorization headers in the request. However you can include any metadata you want to add to the file.
        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 'file=@MyFile.mp4' \
    -F 'folder_id=101' \
    -F 'title=Video.mp4'

        S3 Uploads

        If the customer has chosen to use S3 as their storage backend, you can upload directly to S3 with a singlepart of multipart upload. Our API provides endpoints to sign your S3 uploads. This can only be done if the target folder has S3 storage configured or if a global storage container is configured for all folders.

        If you prefer to upload directly to S3 in a different way, you can upload it to S3 yourself and then call our endpoint POST /api/upload/blob to add the object.
        It's also possible to register an SQS queue to automatically make new objects available in MediaLab without the need to manually call the API. Contact our service desk for more information.

        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.

        Examples

        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. here on GitHub.