Downloading

Files and folders can be downloaded via the Skyfish API. Authorization is possible via URL parameters, so download URLs can be embedded in other applications.

Download a media file

GET /media/:id/download_location returns where to fetch the file:

Field	Description
method	The HTTP method. Always GET for this endpoint
url	The URL from which you can fetch your download

The returned URL is valid for at least 5 minutes (15 when it points straight to storage), so use it right away.

Optional parameters:

Parameter	Description
download_info	A blob of JSON describing the download, e.g. {"on_behalf_of":"Arne","project_id":753}
share_hash	The share hash of a share link containing the media. Not needed if you have download access to the media
user	The user ID the download should be attributed to. Required when downloading Colourbox downloads with API key authentication

Added metadata

When you download a jpeg, tiff or png file, the API writes the Skyfish metadata into the file:

Field	Written to
title	XMP:Title
copyright	EXIF:Copyright, IPTC:CopyrightNotice
description	IPTC:Caption-Abstract
keywords	IPTC:Keywords, XMP:Subject

Download a preview size

GET /media/:id/download_location/:size takes the same parameters and returns the same document, for a preview in one of these sizes (longest side):

110px · 200px · 320px · 480px (or preview) · 800px · 1200px · 1600px

For video only preview applies. It gives you an mp4 video 1280 wide with the height preserving the aspect ratio – for a 16:9 video that is 720p.

URL authorization

The download endpoints GET /media/:id/download, GET /media/:id/download/:size, GET /folder/:id/download and GET /folder/:id/download_location accept the authorization as a URL parameter. GET /media/:id/download_location and GET /media/:id/download_location/:size do not; send the Authorization header (or a share_hash) to those.

The Authorization parameter (capital A) is the base64 encoding of the value of the Authorization header (see Authorizing requests). You don’t need it if you already send the header.

1. Take the header value:

   CBX-SIMPLE-TOKEN Token=b932d2522301db11a33196411bb4b260d9b8d3b5

2. Base64 encode it:

   Q0JYLVNJTVBMRS1UT0tFTiBUb2tlbj1iOTMyZDI1MjIzMDFkYjExYTMzMTk2NDExYmI0YjI2MGQ5YjhkM2I1

3. Add it to the URL:

   https://api.colourbox.com/media/123456789/download?Authorization=Q0JYLVNJTVBMRS1UT0tFTiBUb2tlbj1iOTMyZDI1MjIzMDFkYjExYTMzMTk2NDExYmI0YjI2MGQ5YjhkM2I1

Caution

The URL carries your auth-token: base64 is an encoding, not encryption, so anyone who has the URL can decode the token and use it for any other API request, until the token expires. URLs also end up in browser history, server logs and Referer headers. Only hand the URL to applications and people you would give the token itself, and don’t log it. If an application only needs the file, give it the URL from GET /media/:id/download_location instead: it is short-lived (at least 5 minutes) and grants nothing else.

The URL is valid for as long as the auth-token is.

Download a folder as a ZIP file

POST /folder/:id/zip-file creates a ZIP file with all files and sub folders of the folder. It is asynchronous:

Field	Description
job_id	Used to poll the status of the ZIP file
state	PENDING or DONE
url	null, or the URL to GET the ZIP file from
valid_until	null, or a UNIX timestamp

Poll with GET /zip-file/:job_id or keep posting – both return the exact same data. The job_id contains a slash (e.g. f/3kq9...), so put it in the URL as is, without URL-encoding it.

ZIP64 and unknown size

Due to limitations in the standard ZIP format, ZIP files are delivered in ZIP64 format if the total size is expected to exceed 2 GB. This is an estimate, so you may also get ZIP64 for slightly smaller files. Some platforms, notably older versions of Windows and Mac OS X, do not support ZIP64 natively.

ZIP files are delivered with chunked transfer encoding and no content length, so you will not know the total size until the download has finished.