Chapter 1
Introduction

1.1 General

1.1.1 Getting access to the Skyfish API

In order to get access to the Skyfish API, you need to set up an agreement with Colourbox. Please contact our Sales department by phone at +45 - 70 20 33 15 or by email info@colourbox.com to discover what agreement is right for you.

You can fetch your API key and secret by going to your API settings page at: https://www.skyfish.com/account/api.

1.1.2 API Key

The API key is used to uniquely identify the application that is used to access the Skyfish API. Each application using the Skyfish API must use its own API key and secret. The API key is used for tracking and accounting for the application use. The API key in itself does not grant access to the Skyfish API. Access is only granted in a combination with user credentials.

Using the API key for other applications other than the one agreed upon with Colourbox, sharing the API key and secret or otherwise disclosing the API key and secret to third party will result in the revocation of the API key.

1.1.3 Resources and Verbs

A resource refers to an URL endpoint, e.g. /search is a resource. Resources usually refer to an object that can be retrieved and/or modified, e.g. /media/35 or /user/1337. Some resources in the Skyfish API are not “true” resources, e.g. /search is not a true resource since it cannot be retrieved and modified in the normal sense. All resources must be prefixed with the Skyfish API base-URL:

https://api.colourbox.com.

From here on we omit the API-based URL for brevity.

Actions on the Skyfish API are defined by the HTTP verb used on the resource. If a GET-request is made to the /media/43 resource, a document representing the resource is returned. If a POST-request is made to /user/56, the API expects that the user object is being modified. The following HTTP verbs are used in the Skyfish API:

• GET
• POST
• DELETE

Please note the not all verbs are supported on all resources.

1.1.4 Response Codes and Responses

Overall status of a request is conveyed via HTTP status codes. See C for a list of possible status codes returned by the Skyfish API. Thus, it is important to check the status code of the request before making assumptions about what the request body will contain. In general, if the HTTP status code is in the 200-range, everything went fine. If the request is in the 400-range, it could not be processed due to a user error. If it is in the 500-range, it could not be processed due to a server error.

The response body will, if present, have the content type JSON and contain the output generated from the request. For a GET-request to /search it would be a JSON document describing a search result.

We reserve the right to extend the returned response content from the Skyfish API in order to keep providing needed functionality. Existing content in responses will not be modified for backwards compatibility reasons. A new version of the Skyfish API will be issued in that case. Please ensure that the usage of the response content from the Skyfish API is resilient to these kinds of additions.

1.2 Tutorial: Getting Started with the API

This section is a short walkthrough on how to connect to the Skyfish API and perform a simple search against the API.

To follow the examples, you need to have a valid API key and secret. The API key and secret can be found here: https://www.skyfish.com/account/api You also need curl or equivalent software capable of doing HTTP requests.

1.2.1 Getting Authenticated

The first thing every application needs to do is to get authenticated. This is done by having the user, who is going to use the API, log in. By logging in, the API returns an auth-token, which can be used to authorize subsequent requests to the API. A token is very similar to the “session” concept we know from regular web development.

In order to authenticate against the API we POST the username and password of the user together with the API key, timestamp and a HMAC to /authenticate/userpasshmac endpoint. The HMAC is computed in the following way:

The following example shows how to calculate the HMAC using PHP:

Given that the API key is “company2key”, the secret is “company2secret” and the “timestamp” is 1429187979, the HMAC will then look like this:

We can get an auth-token with curl with the following command:

This will return status code 200 and a JSON document as shown below.

The token in the response should be used on all subsequent calls to the API. A token has a default lifetime of 30 days.

1.2.2 Searching for Images

Next, we can search for images via the API. We will do a search for kittens and ask the API to return a thumbnail URL, a unique media ID and the media caption. The request needs to be authorized; otherwise, it will be rejected. The authorization information, the token acquired in the previous step, is set in the Authorization header. The header will look like this:

To perform the search we make a GET request to the search resource. We specify what we want to search for with the parameter q, the amount of results we want with media_count, and what information about the search results you would like back with return_values. Below is how this can be accomplished with curl:

This will return a status code 200 and a JSON document with the results of the search in the response body. The search result is divided into two parts. The actual result itself which resides in the {response: {media: {[]}} section. This is the media that the search found. The media itself can be pictures, vectors or video.

The second part is statistics about the search. Hits is how many results were found in all, media_count is how many search results where actually returned and media_offset is the offset into the full search result. This can be used for pagination of search results. Please see 4 for more details on options and parameters applicable to the search endpoint.

By default a search will be in all folders owned by the user doing the search. A search can be limited to a subset of the folders a user has access to, by setting the folder_ids on the search request. An example of searching only in one folder can be seen below:

A list of all folders available can be found by doing a request to the /folder resource:

The above call to the API will return a result containing all the folders a company has access to:

More info about the individual folders can be found by going to the /folder/:id endpoint.

1.3 Handling Errors

Every response from the API will return a header called X-Cbx-Request-Id. The header value is a unique ID identifying your request. Should you encounter a request which responds with a status code in the 500 range, we are able to debug the possible problem given that ID.

It is therefore important that you save the ID to make support easier. Below is an example of a response from the API with a 500 status code:

Given the ID 532c00918bfba we will be able to get a little more information about why the request was rejected and help resolve the issue. All support enquiries are to be sent to: api@colourbox.com.

Please refer to C for a list of return codes sent back from the Skyfish API.

1.4 CORS Requests

The Skyfish API accepts CORS requests (Cross-Origin Resource Sharing). The Skyfish API will always send back a Access-Control-Allow-Origin header that matches the Origin header set in the CORS request.

If a preflight request is made to the Skyfish API, the following headers will be sent back:

• Access-Control-Allow-Origin - Will match the content of the Origin header
• Access-Control-Allow-Methods
• Access-Control-Max-Age

The Skyfish API does not support and does not adhere to the following CORS specific headers.

• Access-Control-Request-Method
• Access-Control-Request-Headers
• Access-Control-Allow-Headers
• Access-Control-Allow-Credentials
• Access-Control-Expose-Headers

Chapter 2
Authentication

In order to use the Skyfish API you need to authenticate yourself against the API. The Skyfish API supports the following authentication mechanism:

• Username and Password with HMAC

2.1 Username and Password with HMAC

---

---

You can find your API key and secret in your API settings page at: https://www.skyfish.com/account/api.

2.1.1 POST: /authenticate/userpasshmac

This resource lets you exchange the user’s username and password with a valid HMAC into an auth-token.

Payload

The payload is a JSON document with the following content:

username

Username

password

Password connected to the username

key

API key

ts

Current UNIX timestamp

hmac

HMAC hash. Must be lower case.

Returns

token

An auth-token for request authorization

type

The type of token you have received. This will always be 1 for a user, meaning that the auth-token is bound to a specific user

ownerIdentifier

The user-ID in Colourbox

validUntil

The time to live for the auth-token (UNIX time stamp)

2.1.2 Example

The following is an example on how to retrieve an auth-token via an API using the username, password and a HMAC.

When calculating the HMAC, the following parameters are used (values chosen at random):

apikey

“mykey”

secret

“mysecret”

TS

1383307501

The above will give you the following HMAC for authenticating the request.

The authentication request will now look like this (example via cURL):

And will return a token:

The auth-token can later be used to access resources that require authorization.

2.2 Password Reset

The password reset functionality requires special permission to use. For more information on how to get access, feel free to contact our sales department at: sales@colourbox.com. Password reset can also be done through: www.skyfish.com

---

---

2.2.1 POST: /authenticate/userpass/reset

Request a new password for the username passed to the resource.

Payload

The payload is a JSON document with the following content:

username

Username for which the new password should be set

Return Value

The Skyfish API always returns a 204 status code no matter whether the username is valid or not.

Chapter 3
Authorization

All authorization in the Skyfish API is done through the Authorization header. The Authorization header has the following general syntax.

The auth-schema defines what authentication method is used and the auth-params is a space separated list of key=value fields specific to the individual auth-schema.

The Skyfish API supports the following authorization scheme

• CBX-SIMPLE-TOKEN

3.1 Token-based Authentication

Token-based authorization works by including an auth-token in each request to the Skyfish API. The auth-token is aquired by doing a authentication request to the Skyfish API by one of the supported authentication mechanisms. See 2 for supported authentication schemes.

The received auth-token must be included in every subsequent request through the Authorization header. The syntax for the Authorization header when using token-based authorization is given by the following:

The token-based auth-scheme requires the following auth-param:

Token

The auth-token

3.1.1 Example

The following is an example on how to retrieve an auth-token by sending an authentication request with a username, password and HMAC and then putting it in future Authorization headers:

The auth-token can be used to access resources that require authorization. By using the auth-token b932d2522301db11a33196411bb4b260d9b8d3b5 a request can be made to the media resource. The request vill look as follows:

3.1.2 Validating Existing Tokens

It is possible to validate the status of an existing token via a validation endpoint in the Skyfish API.

---

---

Return Value

The endpoint returns a JSON document with the following keys:

TokenStatus

Have the value ”valid” on valid tokens othervide ”invalid”

Chapter 4
Search

Searching is the primary way of finding media via the Skyfish API.

You can only search in folders that the authenticated user has access to. If you have access to your Colourbox downloads, you can search in these as well. See A for more information.

---

---

4.1 GET: /search

This resource will let you search for your own media content.

4.1.1 Parameters

q optional

The query string that you want to search for, e.g. “cat”. See 4.1.3 for details on which fields are matched.

return_values

Specifies which values you want back. The list should be a string with + as separator, e.g. unique_media_id+keywords. See 4.1.2 for a complete list.

media_count optional

Limits the number of results. Default is 500.

media_offset optional

How many rows should be skipped from the start of the result. Mainly used for pagination.

media_type optional

Specifies the type of media you are searching for, and the value must be one of the following: “image”, “vector”, “video” and “generic”. If not set, we include media from all types. You can specify multiple by separating them with a “+”.

folder_ids optional

Limits the folders in which the search is performed. Multiple folder IDs should be concatenated with “+”

recursive optional

By default you search in exactly the folders specified, if you want to search recursively through the folders specified, set recursive to “true”.

unique_media_id optional

Limits the search to only being done on the given unique medias. Multiple unique media IDs should be concatenated with “+”

date_filter_field optional

If you want to filter by dates, you specify either created, camera_created or last_modified. Created is the point in time when we got a hold of the image. Camera created is the point in time when the picture was taken, given the camera wrote the camera created exif tag. Last modified is the last time we index a metadata update.

min_date optional

Specifies the min. date for the date filter field. 2016-03-14T12:23:51Z. This is greater than or equal.

max_date optional

Specifies the max date for the date filter field. This is less than or equal.

orientation optional

Limits search to media in either “horizontal” or “vertical”

thumbnail_size optional

Returned thumbnail URLs in the selected size, if thumbnail_url or thumbnail_url_ssl is given in return_values. Permissible values are: “110px”, “200px”, “320px”, “480px”, “800px”, “1200px”, “1600px”. By default the “320px” version is returned.

order optional

Order the search result according to either “relevance”, “created” or “distance”. Created is the time the media was imported into the Colourbox system. If “distance” is specified, the latitude and longitude must be provided as parameters as well.

direction optional

Specify the direction of the ordering. Permissible values are “asc” or “desc”. Note that this option can only be given if order is given as well.

resolution optional

Can be specified to either a4 or a3. This will restrict the search result to images which has resolution at least a4 or a3.

min_width optional

Specifies the minimum width.

min_heightoptional

Specifies the minimum height.

query_typeoptional

Specifies the query type. You can specify strict_and_search for a search result which only matches whole words, or wildcards for a result which bends over backwards to provide as many results as possible.

exclude_expired_mediaoptional

Specifies if expired media should be excluded from the search. Default is false

min_expiration_dateoptional

Specifies to only include media with expiration date grater or equal to the date specified. Format: yyyy-mm-dd

max_expiration_dateoptional

Specifies to only include media with expiration date less or equal to the date specified. Format: yyyy-mm-dd

At least one of q, unique_media_id or folder_ids MUST be applied to a search in order to get back a search result.

4.1.2 Return Values

When searching you need to specify which values you need in the result. You need to specify at least one value. The list to choose from is:

keywords

Keywords on media

folder_tags

The keywords inherited from folders

suggested_keywords

The automatic tags found with object recognition

media_type

The media type. Possible values are “image”, “vector”, “video” or “generic”. “generic” covers all file types that Colourbox do not process, e.g. Word documents and the like

height

Height in pixels

width

Width in pixels

unique_media_id

The ID for specific media

folder_id

The folder the media resides in

created

The date the media was imported into Colourbox

title

The title of the media if any

description

The description of the media if any description

thumbnail_url

Publicly accessible URL of the thumbnail. NOTE that the URL is short-lived, 24 hours, signed and not persistent. Do not store these URLs indefinitely. If you desire to cache the result, you should probably cache it for 23 hours at maximum.

thumbnail_url_ssl

Publicly accessible HTTPS URL of the thumbnail. NOTE that the URL is short-lived, 24 hours, signed and not persistent. Do not store these URLs indefinitely. If you desire to cache the result, you should probably cache it for 23 hours at maximum.

filename

The original filename

copyright

Copyright information for the media

camera_created

The date the media was shot if the information was available in metadata when the media was uploaded

byline

The photographer/creator of the media

file_mimetype

The mime type of the media

file_disksize

The size of the media in bytes (this is the size of the file when it was uploaded; the download size typically differs from this since we attempt to patch metadata from our system into the file whether it has been changed since uploading it or not)

uploaded_by

The user ID of the user who uploaded the media

geo_location

The location the image was taken, if available. If the location is available you get {latitude, longitude}, else {}.

consent_forms

The consent forms to which the media has been attached

consent_exempt

Can the media be used without consent

4.1.3 Search Algorithm

The q parameter in a search can consist of several terms. A term being a sequence of letters and numbers separated from other terms by a +. Each term is matched against a subset of the fields on the files. The Skyfish API will try and match the query on the following fields on files:

• keywords
• title
• description
• copyright
• uploaded_by
• filename

It is also possible to exclude a term in the query string. This is done by prefixing the term with a -. There should no space between the hyphen and the term.

Please note that the actual algorithm for doing the search is subject to ongoing changes.

4.1.4 Search Data Normalization

All search data are put in unicode normalization form C (NFC), before added to our search engines. We do this to ensure that searching works efficiently, smoothly and seamlessly when searching with non-latin letters and special characters. All input queries are automatically put in unicode normalization for c as well.

4.1.5 Thumbnails

Skyfish automatically generates thumbnails in all relevant sizes for uploaded images. If you have uploaded non-image media via Skyfish, then generic thumbnails are returned for all extensions known to Skyfish.

Note that generic thumbnails have the same size, no matter what size you have requested. Generic thumbnails have size 93x119 pixels.

4.1.6 Example Request and Response

To get the title and keywords for an image of a cat, the following request should be performed:

Remember to set the authorization header on the request.

This should generate a response that looks like this:

4.2 GET: /search/colourbox/download

This resource will let you search in all of your Colourbox downloads.

It is not possible to get your own media as part of the result on this search endpoint. Please refer to 4.1 for details on how to search in your own material.

You need to have access to your Colourbox downloads in order to use this endpoint. Please see A.

4.2.1 Parameters

This endpoint takes the same parameters as the other search endpoints with the following exceptions:

folder_ids

Is not an allowed parameter

lang optional

specifies a search language. Options are en, da or de. Default is en.

Please see 4.1.1 for a complete list of valid parameters.

4.2.2 Return Values

This endpoint returns the same type of result as the other search endpoints with the following exception:

folder_ids

Is not an allowed parameter

Please see 4.1.2 for a complete list of valid return values.

Chapter 5
Media

The Skyfish API features several ways of fetching and manipulating metadata on files.

---

---

5.1 GET: /media/:id/

Get data for a media

5.1.1 Return Value

The endpoint returns a JSON document with the fields listed in the table below. All fields are read-only except the metadata field.

id

The media ID

created

The time the media was uploaded to Colourbox

type

The media type. Valid values are stock, vector, video and generic

filename

The er original filename of the media

file_md5

MD5 sum of the file

uploaded_by

User ID of the user who uploaded the media

metadata

Part of the media information that can be edited after upload. See 5.2.1 for details on content.

Colourbox downloads can be accessed via this endpoint if you have access. Please see A for more information.

5.2 GET: /media/:id/metadata

Get media metadata sub-document.

5.2.1 Return Value

Return a JSON document with the following content:

editorial

Is the media considered editorial

adult_content

Is the media considerede adult content

keywords

Keywords on the media

title

The title of the media

description

A short description of the media

iptc

IPTC data extracted from the media when it was uploaded

geolocation

Geolocation of the media

camera_created

The time the picture was taken as a UNIX timestamp

The geolocation, camera_created, description, title and keywords are all extracted from the media metadata at the time of the upload into the system, see 9.1.5. Some of the data can be modified afterwards, see 5.3.

5.3 POST: /media/:id/metadata

Update the entire metadata sub-document of the media.

5.3.1 Payload

The payload is a JSON document with the content described in 5.2.1. Note that on title, description and keywords, only en is indexed by the Colourbox search engines for your own files. All languages are indexed on Colourbox media.

5.3.2 Return Value

200 status code on success.

5.4 GET: /media/:id/metadata/expiration_date

Get media expiration date

5.4.1 Return Value

Return a JSON document with the following content:

expiration_date

Is the expiration date of the media (yyyy-mm-dd)

5.5 POST: /media/:id/metadata/expiration_date

Update the expiration date of a media.

5.5.1 Payload

The expiration date can be set in two ways.  5.5.1 or  5.5.1

Setting the date explicit

Setting year and month

In this case the expiration date will be set to the last day in the given month.

5.5.2 Return Value

200 status code on success.

5.6 DELETE: /media/:id/metadata/expiration_date

This endpoint will unexpire media.

5.6.1 Return Value

200 status code on success.

5.7 GET: /media/:id/folders

Get a specific folder a media file recides in.

5.7.1 Return Value

Return a JSON document list which contains elements with the following content:

group_id

The folder ID

status

Is always ”RELEASED”

Please note that this is not a complete representation of a folder. Please see 6 for the full representation.

5.8 POST: /media/:id/folders

Update the folder a media file recides in.

5.8.1 Payload

The payload is a JSON document with content described in 5.7.1.

5.8.2 Return Value

200 status code on success.

5.9 DELETE: /media/:id/folder/:folderId

This endpoint can be used when you simply want to remove a media file from a folder.

5.10 POST: /media/:id/folder/:folderId/move_to_trash

Moves a media file to the authenticated user’s trashcan. If the media is already in the trashcan (or a subfolder) it is permanently deleted.

5.11 GET: /media/:id/version

Get the media version number.

A media’s version number is incremented each time the media is modified. This can be the physical media or the metadata, and it can help you determine whether you have the latest version of a media file.

5.11.1 Return Value

The endpoint returns a JSON document with the media version number.

The version will be 1 immediately after upload.

5.12 GET: /media/:id/tags

Get the media’s exiftool tags. These are extracted using exiftool -j -g -n during import.

Chapter 6
Folder

The primary way of organizing media in the Skyfish API is through folders. Folders can easily be handled and modified through the Skyfish API.

---

---

6.1 GET: /folder

Get all folders for the authenticated identity. The list of returned folders can be filtered in several ways. See list of parameters for filter options.

6.1.1 Parameters for Filtering

q optional

Query string matching against the folder name

id optional

Limit the list to the folder that has the given ID. Multiple IDs can be given seperated by “+”

parent optional

Limit the list to folders with the parent ID specified

company_id optional

Limit the list to folders owned by the company. Default behaviour.

exclude_per_user_system_folders optional

Exclude user-specific system folders. Currently this only excludes a user’s own trashcan (all other system folders are company-specific).

The result can also be sorted:

6.1.2 Parameters for Sorting

sort_by optional

Specifies which field you would like to sort by, currently name and created is supported.

sort_order optional

Can be either asc, desc or left out for asc.

6.1.3 Return Value

Return a JSON document list which contains elements with the following content:

id

The folder ID

name

The folder name

parent

The folder ID of the parent folder. NULL if no parent folder exists

company_id

company ID of the company owning the folder

permissions

folder permissions (see table below)

6.2 POST: /folder

Create a new folder.

6.2.1 Payload

The payload is a JSON document with the following content:

name

The folder name

parent

The folder ID of the parent folder. NULL if no parent folder exists

company_id optional

Company ID of the company owning the folder

6.2.2 Return Value

Return a JSON document containing a representation of the newly created folder.

6.3 GET: /folder/:id

Get a given folder

6.3.1 Return Value

The endpoint returns a JSON document with the following keys:

id

The folder ID

name

The folder name

parent

The folder ID of the parent folder. NULL if no parent folder exists

company_id

Company ID of the company owning the folder

created

The time the folder was created

6.4 POST: /folder/:id

Update a given folder.

6.4.1 Payload

The payload is a JSON document with the following content:

name

The folder name

parent

The folder ID of the parent folder. NULL if no parent folder exists

company_id optional

Company ID of the company owning the folder

6.4.2 Return Value

The endpoint returns a JSON document with the updated representation containing the following keys:

id

The folder ID

name

The folder name

parent

The folder ID of the parent folder. NULL if no parent folder exists

company_id

Company ID of the company owning the folder

created

The time the folder was created

6.5 DELETE: /folder/:id

Delete a given folder.

6.6 POST: /folder/:id/purge

Deletes everything below a folder. It is like DELETE, except it does not delete the folder itself.

6.7 Permissions

These flags specify folder properties and what a user can do with a given folder:

---

---

Chapter 7
Cliques

Cliques is a way of grouping people together and giving them access to one or more folders as a group. You must be an admin on Skyfish to manage the cliques.

---

---

7.1 POST: /clique

This endpoint will create a new clique. The payload is a JSON document with the following contents:

name

The name of the clique

skyfish_id

The Skyfish the clique will belong to

thumbnail_id optional

A unique media ID, you would like to use as a thumbnail for the clique

7.1.1 Return Value

A JSON document with the name, skyfish_id, thumbnail_id and the ID of the clique itself.

7.2 POST: /clique/:id

This endpoint will update a clique. The payload is a JSON document with the following contents:

name

The name of the clique

skyfish_id

The Skyfish the clique will belong to

thumbnail_id optional

A unique media ID, you would like to use as a thumbnail for the clique

7.2.1 Return Value

A JSON document with the name, skyfish_id, thumbnail_id and the ID of the clique itself.

7.3 GET: /clique

This will return all the cliques you can manage.

7.3.1 Return Value

A JSON document with a list of cliques.

7.4 DELETE: /clique/:id

This will delete the clique.

7.5 GET: /clique/:id/member

Returns a list of cliques to user memberships.

7.5.1 Return Value

A JSON document with a list of cliques to user memberships.

7.6 POST: /clique/:id/member/:user_id

Add a user to a clique. No payload necessary.

7.6.1 Return Value

A JSON document with the clique to user membership.

7.7 DELETE: /clique/:id/member/:user_id

Remove a user from a clique. No payload necessary.

7.8 GET: /clique/:id/folder

Returns a list of clique to folder memberships.

7.8.1 Return Value

A JSON document with a list of cliques to folder memberships.

7.9 POST: /clique/:id/folder/:folder_id

Add a folder to a clique. The payload is a JSON document with fields:

access

Can be either READ or WRITE

upload

Can be true or left out

7.9.1 Return Value

A JSON document with the clique to folder membership.

7.10 DELETE: /clique/:id/folder/:folder_id

Remove a user from a clique. No payload necessary.

Chapter 8
Download

Files and folders can be downloaded via the Skyfish API. Authorization is possible via URL parameters, so the embedding of downloaded URLs is possible.

---

---

8.1 GET: /media/:id/download_location

Get the downloaded location for a given media

8.1.1 Parameters

download_info optional

A blob of json which describes the download, an example could be
{"on_behalf_of":"Arne","project_id":753}

authorization optional

base64 encoded authorization information.

user optional

Set the user ID the download should attributed to. This is a requirement if downloading Colourbox downloads and API key authentication is used.

8.1.2 Return Value

Returns a JSON document describing method and URL for fetching your download.

method

The HTTP method. Is always GET for this endpoint.

url

The URL from which you can fetch your download

The returned URL will be valid for 5 minutes.

8.1.3 Added Metadata

When you download either a jpeg, tiff or png file from the Skyfish API, the API adds EXIF data. The table below lists where the different fields from the Skyfish API is placed in EXIF data.

title

XMP:Title

copyright

EXIF:Copyright, IPTC:CopyrightNotice

description

IPTC:Caption-Abstract

keywords

IPTC:Keywords, XMP:Subject

8.2 GET: /media/:id/download_location/:size

Get download location for a given media

8.2.1 Parameters

The size can have the following values:

110px

110 px on the longest side

200px

200 px on the longest side

320px

320 px on the longest side

480px

480 px on the longest side

800px

800 px on the longest side

1200px

1200 px on the longest side

1600px

1600 px on the longest side

Note that for video only preview applies. This will give you an mp4 video with width 1280 and height to preserve aspect ratio. If this aspect ratio of your video is 16:9, this can be considered 720p.

download_info optional

A blob of json which describes the download, an example could be
{"on_behalf_of":"Arne","project_id":753}

authorization optional

base64 encoded authorization information.

user optional

Set the user ID the download should attributed to. This is a requirement when downloading Colourbox downloads and API key authentication is used.

8.2.2 Return Value

Returns a JSON document describing method and URL for fetching your download.

method

The HTTP method. Is always GET for this endpoint.

url

The URL from which you can fetch your download

The returned URL will be valid for 5 minutes.

8.3 URL authorization

The content of the Authorization parameter is a base64 encoding of the value of the normal authorization header. See 3 for details on how to calculate the content of the authorization header for the different authorization schemes.

Note that you do not have to specify the Authorization parameter if you have already specified the Authorization header.

8.3.1 Example

This example shows how to download a media file using URL authorization. Normal header authorization is still possible. First you calculate the authorization information, see 3 for details.

Then base64 encodes the authorization information above.

Finally the authorized URL looks like this.

The URL above can be directly embedded into any third party application. The validity time of the URL depends on what authorization schema is used.

8.4 POST: /folder/:id/zip-file

Create a zip file from the folder. The zip file will contain all files and sub folders.

The creation of the zip file is asyncronous and will take some time to complete. Instructions on how to poll for status follows below.

8.4.1 Return value

job_id

is a string used to poll the status of the zip file

state

is either PENDING or DONE

url

is either null or a string which you can GET to retrieve the zip file

valid_until

is either null or a int unix timestamp

You can poll by GET /zip-file/:job_id or keep posting. Both endpoints return the exact same data.

8.4.2 ZIP files

Due to technical limitations in the standard ZIP format, zipped files are automatically delivered in ZIP64 format if the total size is expected to exceed 2 GB. This is based on an estimate, so you may also receive ZIP64 files when the total size is slightly smaller than 2 GB. Some platforms, notably older versions of Windows and Mac OS X, do not support ZIP64 natively, and users will have to acquire 3rd party software to be able to unpack ZIP64 files.

Chapter 9
Upload

The Skyfish API provides the ability to upload files to your account. The process is a multi-step operation.

9.1 Upload Process

Uploading is comprised of 3 stages

• Register upload
• Upload file
• Finalize upload

9.1.1 Register Upload

First the upload needs to be registered with the API. This is done with a POST request to /upload/register with a payload telling the API in what folder the file should be placed and optionally a URL for redirection after the upload is done. The API will deliver a set of fields that needs to be posted together with the actual file being uploaded.

9.1.2 Upload

Upload is done with a multipart POST request to the URL received from the API in the previous (register) step. All fields must be posted, in the received order, for the upload to succeed. The file to be uploaded must be placed in the file field and the file field must be last field as everything after the file field is ignored. The POST will automatically redirect to a URL that will trigger the finalizing of the upload.

9.1.3 Finalizing the Upload

After posting the file, the upload needs to be finalized. If your client automatically follow redirects from the upload operation itself, then the finalizing is done automatically. If your client do not follow redirects automatically, then you must finalize the upload manually by doing a GET request to the value of the Location header received from the upload request. If redirectURL was provided when registered the upload, the API will redirect to that URL with the id of the uploaded media in the query string with media_id as key. If you have not registered your upload with a redirectURL, the API will return a JSON document containing the media_id of the uploaded file.

Import Status

After the upload has been finalized, the media is sent to Colourbox’ internal import service that will extract information from the media, create thumbnails, previews, etc. To see the progress of the import you can make a GET request to /media/<media_id>. If the media is being imported you will receive a 202 status code together with the progress in percentages. When the import is done, you will receive a 200 status code and a representation of the media.

9.1.4 Doing upload with other clients than browsers

The data structure returned from /upload/register is optimized for HTML form generation. You need to substitute ${filename} with the filename of the uploaded file, if you are not setting the filename in the Content-Disposition for the file field.

9.1.5 Extracted Metadata

The API extracts several pieces of information from the uploaded medias EXIF data. This information is made searchable by the API. The following table describes from which fields in the EXIF data these pieces of information are extracted from.

title

XMP:title, IPTC:Headline, IPTC:ObjectName, IPTC:Caption-Abstract

description

XMP:Description, EXIF:ImageDescription, IPTC:Caption-Abstract

keywords

IPTC:Keywords

copyright

IPTC:CopyrightNotice

photographer

IPTC:ByLine, IPTC:ByLineTitle

NOTE that the API will only extract the first field that matches.

9.2 Resources

---

---

9.3 POST: /upload/register

Register an upload with the API.

9.3.1 Payload

The payload of the request is a JSON document describing what folder in which the upload file should be placed.

folder

The folder ID of the folder where the uploaded media will be placed.

redirectURL optional

Where to redirect to after the upload is done.

9.3.2 Return Value

The resource returns a JSON document with all the information needed to upload the actual file. It contains the endpoint to post the file to, the encoding type of the POST request and the POST parameters that should be posted along with the file itself. The file itself should be posted in the file field.

The JSON documents is a direct representation of an HTML form.

Chapter 10
Company

The Skyfish API provides various utility endpoints for the companies that have access to the Skyfish API.

---

---

10.1 GET: /company/:id/users

Get all users connected to the company.

10.1.1 Return Value

A JSON document containing a list of users connected to the company.

10.2 GET: /company/:id/apikeys

Get the API key and secret for the company.

10.2.1 Return Value

A JSON document containing the key/secret combination for the company.

10.3 GET: /company/:id/apiendpoint

Get the API endpoint for the company.

10.3.1 Return Value

A JSON document containing the protocol and host for the company.

Chapter 11
User

The Skyfish API provides various utility endpoints for the individual users that have access to the Skyfish API.

---

---

11.1 GET: /user/:id/folders

Get all folders the user have access to,

11.1.1 Return value

A JSON document containing a list of folder the user have access to. Each subelement describes a folder with the following content

id

The folder id

name

The folder name

parent

Parent folder id

company_id

The company Id of the owning company

created

The time the folder was created

permissions

The permissions the user have on the folder. See 11.1.2

11.1.2 Folder permissions

Folder comprises of 3 disjoint permission groups. A User must have at lease one of these in order to interact with the folder.

READ

Gives read access to the folder

WRITE

Gives write access to the folder including upload access

ADMIN

Gives admin access to the folder including adding other users to the folder.

Note that no permission group implies other permission groups.

11.2 GET: /user/:id/profileimage(/:size)

Get the users profile image in a given size. By default if the size is not given, the small version is returned.

11.2.1 Parameters

The size can have the following values:

small default

25x25 px cropped version

medium

50x50 px cropped version

large

100x100 px cropped version

original

The original unaltered profile image

11.2.2 Return value

The Skyfish API return the image with the following format {small,medium,large,original}_USERID.jpg

11.3 GET: /user/:id/clique

Get all clique the user is a member of.

11.4 POST: /user/:id/profileimage

Upload a new profile image for the user.

11.4.1 Payload

The payload of the request is the file being uploaded.

file

The parameter containing the file

The content type of the POST must be set to multipart/form-data.

11.4.2 Return value

The Skyfish API return a 201 status code on successful upload.

Chapter 12
Disk usage

You can query the Skyfish API for disk usage information, both on a per user basis and for an entire company.

---

---

12.1 GET: /user/:id/diskusage

Get the users disk usage for the different Skyfish that the user have access to.

12.1.1 Return value

A JSON document containing a list of company IDs and the associated disk usage.

company_id

The company id

diskusage

The disk usage in bytes

12.2 GET: /company/:id/diskusage

Get the companys disk usage and the maximum allow disk space.

12.2.1 Return value

A JSON document containing the amount of space used and the maximum amount of spaces the company is allowed to use.

used

The amount of space used in bytes

max

The maximum amount of space allowed to be used in bytes

Chapter 13
Skyfish signup

The Skyfish signup functionality requires special permission to use. For more information on how to get access feel free to contact our sales department at sales@colourbox.com. Password reset can also be done via www.skyfish.com

---

---

13.1 POST: /signup

Request the creation of a new Skyfish Free. A Skyfish Free gives access to 1 GB of storage and 10 users. Payment information is not needed, but is requested if the Skyfish Free is upgraded to a payed version of Skyfish. Upgrade is done via the Skyfish web page.

13.1.1 Payload

The payload is a JSON document with the following content.

name

The full name of the user creating the new Skyfish

email

The users email address

password

A self chosen password

locale

RFC 5646 language tag

A RFC 5646 language tag is a ISO 369-1 language code combined with a ISO 3166 country code.

13.1.2 References

• https://tools.ietf.org/html/rfc5646
• https://en.wikipedia.org/wiki/IETF_language_tag

13.1.3 Return value

The endpoint returns a JSON document with information on the newly created Skyfish containing the following keys.

company

Containing id and reference to the newly created company

user

containing id and reference to the newly create user

Appendix A
Colourbox Downloads

It is possible to get access to your old Colourbox downloads via the Skyfish API. For information on how to get access to your old colourbox downloads feel free to contact our sales department at sales@colourbox.com.

The difference between you own media and Colourbox downloads is that you only have read access to the downloads. This mean that you cannot change metadata or move them to different folders. I you need to move a Colourbox download to one of your own folders, then you must download the media and there after upload it to your own folder.

You have the same search capabilities for your Colourbox downloads as you do with your own medias. Further more you have the possibility to do search in all the Colourbox supported languages. Please see 4.2 for more information.

The following endpoints support Colourbox downloads.

---

---

When downloading a preview you can choose from the same sizes as in ??.

Appendix B
Words explained

B.1 UNIX timestamp

This is the number of elapsed seconds since 00:00:00 Universal Time Coordinated (UTC), Thursday, 1 January 1970. We use it to restrict the validity of your HMAC to a narrow time window. When we receive your request, the timestamp must be within 60 seconds of the current timestamp; otherwise, the request is rejected with a 401 HTTP response code.

B.1.1 References

• http://en.wikipedia.org/wiki/Unix_time

B.2 CORS

Cross-origin resource sharing (CORS) is a mechanism that allows many resources (e.g. fonts, JavaScript, etc.) on a web page to be requested from another domain outside the domain the resource originated from. In particular, JavaScript’s AJAX calls can use the XMLHttpRequest mechanism. Such “cross-domain” requests would otherwise be forbidden by web browsers, per the same origin security policy. CORS defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request. It is more useful than only allowing same-origin requests, but it is more secure than simply allowing all such cross-origin requests.

B.2.1 References

• http://www.html5rocks.com/en/tutorials/cors/
• http://www.w3.org/TR/cors/

Appendix C
HTTP status codes

The statuses of all requests sent to the Skyfish API are conveyed via HTTP status codes:

200

Success
The request was successful. On GET requests the result is located in the body of the request

201

Created
The request was successful. Returned if you are creating new resources.

202

Accepted
The request has been accepted for processing, but the processing has not been completed, e.g. importing a media.

400

Bad request
Your request contains bad syntax and the API could not understand it.

401

Unauthorized
You need to be logged in to access the resource

403

Forbidden
You do not have access to this resource. It will help to authenticate.

404

Not found
The requested resource does not exist. This is also returned if the method is not allowed on the resource.

409

Conflict
We encountered a conflict when trying to process your update. Try applying your update again.

500

Server error
We encountered a problem parsing your request and can not say what went wrong. Please provide us with the “X-Cbx-Request-Id” from the response as it will help us debug the problem.