Download

The Ubstream API allows you to download medias with a GET request to three different endpoints:

• To download a single media, call Download media
• To download a selection of media, call Download selection
• To download all the media from a collection, call Download collection

Several options are available (see the endpoints documentation). With some options, additional resources may have to be generated before the download is possible. These options are quality: 'lower' and includesFulltext: true. If these options are selected and the required resources have not been already generated, the download result won't include the corresponding medias and will instead include a diagnose for each missing resource. The diagnose will have this format:

[
    {
      "$severity": "error",
      "$title": "my-file-title",
      "$message": "An error occurred while downloading media",
      "$detail": "Resource is unavailable and will be generated asynchronously"
    }
]

To prevent this, you need to call the adequate "prepare" endpoint before starting a download. These endpoints are:

• For a single media, call Prepare media
• For a selection of media, call Prepare selection
• For a collection, call Prepare collection

Use the exact same parameters that you would use for the actual download. The result is an object with the requestId attribute:

{
    "requestId": "d9679d87-f074-4da0-9528-99ce2c7bc799"
}

With the requestId, wait for the request completion, as described in the documentation for Asynchronous requests.

Once you get the completed status, you can call the download endpoint. The result can have two different formats: - If you downloaded a single file (one media with only one version and no additional options), the result is the file itself. - If you downloaded multiple files (several medias, one media with several versions or special options like includesFulltext or includesMetadata), the result is a zip file containing all the requested files.

In the case of multiples files, you'll find inside the zip file a special file named diagnoses.json. This file contains a "diagnose" for each downloaded media, the diagnose being either an error or a success with this format:

[
    {
      "$severity": "success",
      "$title": "my-file-title",
      "$message": "Media successfully downloaded"
    }
]