Agent Downloads | Iconik Developers Documentation

What can be downloaded

A download request names one or more things to download. Each kind has its own list in the request body, and a single request may mix them.

Where an entry takes a format, that is a format name as it exists in Iconik: ORIGINAL, ICONIK_PROXY and SUBTITLES are the built-in ones, and a system can define its own. DOWNLOAD_ALL_FORMATS is not a format but an instruction to download every format that is online. The reference lists the field as a string because the set is open.

Assets: assets, each with an assetId and a format. The Agent looks for that format on an online storage and downloads it. Pass DOWNLOAD_ALL_FORMATS as the format to get every format that is online.
Asset versions: assetVersions, each with a versionId, an assetId and a format, for downloading a version other than the latest.
Collections: collections, each with a collectionId and a format. The Agent walks the collection and its sub collections, downloads every asset that has the format, and recreates the collection structure as folders on disk.
Playlists: playlists, each with a playlistId and a format, which downloads the assets on the playlist.
File sets: fileSets, each with a fileSetId and the assetId it belongs to. The format is implied by the file set.
Files: files, each with an assetId and a fileId, for single files. The format is implied by the file.

Starting a download

POST /download-requests queues the download and answers with the download requests that were created. The Agent comes to the front while it handles the request, so the user sees what is happening and can answer any dialog it needs to show.

curl -X POST http://localhost:6286/download-requests \
  -H 'Content-Type: application/json' \
  -H 'App-ID: APP-ID' \
  -H 'Iconik-Host: app.iconik.io' \
  -H 'Auth-Token: AUTH-TOKEN' \
  -d '{
    "assets": [{"assetId": "ASSET-ID", "format": "ORIGINAL"}],
    "collections": [{"collectionId": "COLLECTION-ID", "format": "DOWNLOAD_ALL_FORMATS"}]
  }'

[
  {
    "id": "01JB2X...",
    "title": "My asset",
    "objectIdentity": {"type": "asset", "id": "ASSET-ID"}
  }
]

The authentication headers are optional; leave them out to download as the user already logged in to the Agent. See Authentication for what the Agent does with them.

Two query parameters change how the request is handled:

open_in_fcp: Set to 1 or true to have the Agent open the files in Final Cut Pro once they are downloaded.
resolve_on_local_isg: Set to 1 or true to have the Agent look for the files on a local Iconik Storage Gateway rather than downloading them.

A request that names nothing to download is answered with 400. If the Agent cannot resolve anything to download, or the user cancels a dialog, the request succeeds with an empty list.

Where the files end up

Downloads go to the download location set in the Agent preferences. If the user has set the Agent to ask for a location every time, it asks for this download too, even though it was started over the API, and returns an empty list if the user cancels that dialog.

Individual assets and files can override the location with an outputPath on the entry in the request body. Entries that carry an outputPath are not prompted for. Collections, file sets and asset versions always use the Agent's location.

Following the progress

There are two objects to keep track of.

Download request: What was asked for. One request groups the downloads it turned into: a collection request groups every asset found in that collection and its sub collections, an asset requested in all formats groups one download per format. Even a single asset gets a request, referencing that one download. List them with GET /download-requests and GET /download-requests/{id}.
Download item: One actual download, carrying its status and the files it is writing. List them with GET /downloads and GET /downloads/{id}, or, for one request's items, GET /download-requests/{id}/downloads.

A download item names the request it belongs to in requestItemId, what it is downloading in objectIdentity, and each file it writes in files, with the file name, the full path on disk, the number of bytes downloaded so far and, once known, the total size.

curl http://localhost:6286/downloads

{
  "objects": [
    {
      "id": "01JB2Y...",
      "requestItemId": "01JB2X...",
      "status": {"type": "active"},
      "objectIdentity": {"type": "asset", "id": "ASSET-ID"},
      "files": [
        {
          "fileId": "FILE-ID",
          "fileName": "my_asset.mov",
          "fullPath": "/Users/me/Downloads/my_asset.mov",
          "downloaded": 10485760,
          "size": 52428800
        }
      ]
    }
  ]
}

The status is one of enqueued, resolving, active, paused, completed or failed. A failed status also carries a code and a message.

Pausing and resuming

PATCH /downloads/{id} changes the status of a single download. Only active and paused are accepted; anything else is answered with 400.

curl -X PATCH http://localhost:6286/downloads/01JB2Y... \
  -H 'Content-Type: application/json' \
  -d '{"status": {"type": "paused"}}'

Cancelling

Cancelling works on whole download requests, not on single downloads. DELETE /download-requests/{id} cancels the request and everything it groups, and answers with 204.