Chapter 1
Introduction

1.1 Disclaimer

This document is a work in progress describing the current status of the Skyfish API. Any inconsistencies between the API and this document are not intentional. If you find errors – or have ideas for improvements – please send an email to: api@skyfish.com.

1.2 Version

The current version of the Skyfish API is ”Version 1”. The content of this documentation adheres to the first version of the Skyfish API.

If any large changes are needed, these will then be added to the current version of the Skyfish API. The version will consequently be given a new name, e.g. Version 1 containing the new changes will then become ”Version 2”. We reserve the right to introduce new functionality without breaking backwards compatibility.

1.2.1 Version 1

This is the first version of the Skyfish API.

Deprecation Notice

HMAC and token-based authentication based on an API key and a secret will be deprecated in future versions in favour of user-based authentication.

Username and password authentication will be deprecated in favor of a username and password with HMAC authentication.

1.2.2 Version 2

This will be the next major version of the Skyfish API.

1.3 General

1.3.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.3.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.3.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:

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

1.3.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.4 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.4.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:

Listing 1.1: Computing the HMAC
1HEX(HMAC-SHA1(secret, apikey + ":" + ts))

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

Listing 1.2: Computing the HMAC in PHP
1hash_hmac(sha1, $apikey . ":" . time(), $secret);

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

Listing 1.3: Computed HMAC
17e42196943a343e7494fc2636a3f7313edfcd81f

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

Listing 1.4: Authorization Request with Curl
1curl -d ’{"username":"ausername","password":"verysecret","key":"company2key","ts":1429187979,"hmac":"7e42196943a343e7494fc2636a3f7313edfcd81f"}’ https://api.colourbox.com/authenticate/userpasshmac

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

Listing 1.5: Authorization Response
1{ 
2  "validUntil" : 14391887979, 
3  "type" : 1, 
4  "ownerIdentifier": 645654, 
5  "token": "0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b", 
6}

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.4.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:

Listing 1.6: Authorization Header
1Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b

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:

Listing 1.7: Search Request with Curl
1curl -H "Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b" "https://api.colourbox.com/search?q=kitten&media_count=10&return_values=thumbnail_url+unique_media_id+title"

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:

Listing 1.8: Search Request with Folder IDs Using Curl
1curl -H "Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b" "https://api.colourbox.com/search?q=kitten&media_count=10&return_values=thumbnail_url&folder_ids=42"

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

Listing 1.9: Folder Request with Curl
1curl -H "Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b" https://api.colourbox.com/folder

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

Listing 1.10: Folder Response
1[ 
2  { 
3    "company_id" : 1995, 
4    "parent" : null, 
5    "name" : "My first folder", 
6    "id" : 42 
7  }, 
8  { 
9    "company_id" : 1995, 
10    "parent" : null, 
11    "name" : "Pictures", 
12    "id" : 1337 
13  } 
14]

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

1.5 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:

Listing 1.11: Error Response Including Headers
1< HTTP/1.1 500 Internal Server Error 
2< Server: nginx/1.4.4 
3< Date: Fri, 21 Mar 2014 09:04:17 GMT 
4< Content-Type: application/json 
5< Transfer-Encoding: chunked 
6< Connection: keep-alive 
7< X-Powered-By: PHP/5.5.7 
8< X-Cbx-Request-Id: 532c00918bfba 
9< X-Cbx-Host-Ip: 10.74.132.253 
10< 
11{"message":"Server error"}

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.6 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:

The Skyfish API does not support and does not adhere to the following CORS specific 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:

2.1 Username and Password with HMAC


Verb Resource

Description




POST /authenticate/userpasshmac

Given an username, a password and a valid HMAC returns an auth-token.


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

Listing 2.1: Calculating the HMAC Hash in PHP
1echo hash_hmac(sha1, mykey:1383307501, mysecret);

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

Listing 2.2: Authorization Header Value
184b252e61bd800f33fcd58fb006a0f01377ec979

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

Listing 2.3: Token-based Authentication Request
1curl -d ’{"username":"palle","password":"bilka","key":"mykey","ts":1383307501,"hmac":"84b252e61bd800f33fcd58fb006a0f01377ec979b252e61bd800f33fcd58fb006a0f01377ec979"}’ https://api.colourbox.com/authenticate/userpasshmac

And will return a token:

Listing 2.4: Token Response
1{ 
2  "validUntil" : 1424940265, 
3  "type" : 1, 
4  "ownerIdentifier": 645654, 
5  "token": "b932d2522301db11a33196411bb4b260d9b8d3b5", 
6}

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


Verb Resource

Description




POST /authenticate/userpass/reset

Given a username a new password is requested.


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.

Listing 3.1: Authorization Header Syntax
1Authorization: <auth-schema> <auth-params>

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

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:

Listing 3.2: Token-based Authorization Header Syntax
1Authorization: CBX-SIMPLE-TOKEN Token=<...>

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:

Listing 3.3: Token-based Authentication Request
1curl -d ’{"username":"palle","password":"bilka","key":"mykey","ts":1383307501,"hmac":"84b252e61bd800f33fcd58fb006a0f01377ec979b252e61bd800f33fcd58fb006a0f01377ec979"}’ https://api.colourbox.com/authenticate/userpasshmac

Listing 3.4: Token Response
1{ 
2  "token":"b932d2522301db11a33196411bb4b260d9b8d3b5", 
3  "type":1, 
4  "ownerIdentifier":3232, 
5  "validUntil":1384389501 
6}

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:

Listing 3.5: Token-based Authenticated Request
1curl -H "Authorization: CBX-SIMPLE-TOKEN Token=b932d2522301db11a33196411bb4b260d9b8d3b5" https://api.colourbox.com/media/42343

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.


Verb Resource

Description




GET /authenticate/simpletoken/:tokenString

Validate token


Return Value

The endpoint returns a JSON document with the following keys:

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

Listing 3.6: Response Example
1{ 
2  "TokenStatus" : "valid" 
3}

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.


Verb Resource

Description




GET /search

Lets you search in your media

GET /search/colourbox/download

Lets you search in your Colourbox downloads


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 {}.

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:

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:

/search?q=cat&return_values=title+keywords&media_count=1

Remember to set the authorization header on the request.

This should generate a response that looks like this:

1{ 
2   "response" : { 
3      "hits" : 34497, 
4      "media" : [ 
5         { 
6            "keywords" : [ 
7               "cat ", 
8               "cute ", 
9               "purebred ", 
10               "animal ", 
11               "attentive ", 
12               "beautiful ", 
13               "bow ", 
14               "domestic ", 
15               "feline ", 
16               "fur ", 
17               "furry ", 
18               "gaze ", 
19               "head ", 
20               "look ", 
21               "mammal ", 
22               "nose ", 
23               "pedigree ", 
24               "pedigreed ", 
25               "pet ", 
26               "portrait ", 
27               "pretty ", 
28               "shorthair ", 
29               "sideburns ", 
30               "stare ", 
31               "sweet ", 
32               "watchful ", 
33               "watching ", 
34               "whiskers ", 
35               "white background " 
36            ], 
37            "title" : "Cat with blue eyes over white background" 
38         } 
39      ] 
40   } 
41}

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.


Verb Resource

Description




GET /media/:id/

Get media document

GET /media/:id/metadata

Get media metadata document

POST /media/:id/metadata

Update media metadata document

GET /media/:id/metadata/expiration_date

Get media expiration date

POST /media/:id/metadata/expiration_date

Update media expiration date

DELETE /media/:id/metadata/expiration_date

Delete media expiration date

GET /media/:id/folders

Get the folders the media recides in

POST /media/:id/folders

Update the folders the media recides in

DELETE /media/:id/folder/:folderId

Remove a media file from a folder

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

Move a media file to trashcan

GET /media/:id/version

Get media download version

GET /media/:id/tags

Get media exiftool tags


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.

Listing 5.1: Response Example (truncated)
1{ 
2  "id": "90909090", 
3  "created": "2014-03-06 12:59:10", 
4  "type": "Stock", 
5  "filename": "COLOURBOX4747447.jpg", 
6  "file_md5": "5fe5b4ebfb16aa787c6fdaa3dce6f844", 
7  "uploaded_by": 42, 
8  "metadata": { 
9    "editorial": false, 
10    "adult_content": false, 
11    "keywords": { 
12      "en": [ 
13        "attractive", 
14        "beach", 
15        "beautiful", 
16        ... 
17      ] 
18    }, 
19    "title": { 
20      "da": "Ung smuk blond kvinde med hat p en strand", 
21      "en": "Young beautiful blond woman with hat on a beach", 
22      "de": "Junge schne blonde Frau mit Hut am Strand", 
23    }, 
24    "description": { 
25      "de": "Junge schine blonde Frau mit Hut zu Fu entlang am Strand Blick auf das Meer", 
26      "en": "Young beautiful blond woman with hat walking along on a beach looking at the sea", 
27      "da": "Ung smuk blond kvinde med hat gr p en strand og ser p havet" 
28    }, 
29    "iptc": { 
30      "Keywords": [ 
31        "attractive", 
32        "beach", 
33        "beautiful", 
34        ... 
35      ], 
36      "Caption-Abstract": "Young beautiful blond woman with hat on a beach", 
37      "ApplicationRecordVersion": 0 
38    }, 
39    "geolocation": null 
40  } 
41}

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

Listing 5.2: Metadata Document Example
1{ 
2   "iptc" : { 
3      "CopyrightNotice" : "Jacob Hansen", 
4      "CodedCharacterSet" : "\u001b%G", 
5      "ApplicationRecordVersion" : 4, 
6      "EnvelopeRecordVersion" : 4, 
7      "Keywords" : [ 
8         "boy", 
9         "combine", 
10         "harvester", 
11         "spring" 
12      ] 
13   }, 
14   "camera_created" : 1407256925, 
15   "geolocation" : { 
16      "source" : "999", 
17      "longitude" : "11.5062", 
18      "latitude" : "52.4242" 
19   }, 
20   "description" : { 
21      "en" : "Boy sitting in the front of the cab in a combine harvester", 
22      "de" : "", 
23      "da" : "" 
24   }, 
25   "keywords" : { 
26      "en" : [ 
27         "boy", 
28         "combine", 
29         "harvester", 
30         "grain", 
31         "summer" 
32      ] 
33   }, 
34   "editorial" : false, 
35   "adult_content" : false, 
36   "title" : { 
37      "en" : "Boy in combine harvester", 
38      "de" : "", 
39      "da" : "" 
40   } 
41}

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.

Listing 5.3: Payload Example
1{ 
2  "editorial": false, 
3  "adult_content": false, 
4  "keywords": { 
5    "en": ["keyword1","keyword2"] 
6  }, 
7  "title": { 
8    "en": "Title" 
9  }, 
10  "description": { 
11    "en": "Description" 
12  }, 
13  "iptc": { 
14    "Keywords":["keyword1", "keyword2"], 
15    "Caption-Abstract":"title" 
16  }, 
17  "geolocation" : { 
18    "source" : "1000", 
19    "longitude" : "7.26627", 
20    "latitude" : "43.7034" 
21  }, 
22}

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)

Listing 5.4: Metadata Expiration date Document Example
1{ 
2   "expiration_date" : "2017-09-11" 
3}

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

Listing 5.5: Payload Example. Specifying a full date
1{ 
2    "expiration_date" : "2017-09-11" 
3}

Setting year and month

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

Listing 5.6: Payload Example. Specifying only year and month
1{ 
2    "expiration_year" : "2017", 
3    "expiration_month" : "09" 
4}

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.

Listing 5.7: Media Folder List Example
1[ 
2  { 
3    "group_id" : 202557, 
4    "status" : "RELEASED" 
5  }, 
6  { 
7    "group_id" : 392791, 
8    "status" : "RELEASED" 
9  }, 
10  { 
11    "group_id" : 392873, 
12    "status" : "RELEASED" 
13  } 
14]

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.

Listing 5.8: Media Folder List Example
1[ 
2  { 
3    "group_id" : 202557, 
4    "status" : "RELEASED" 
5  }, 
6  { 
7    "group_id" : 392791, 
8    "status" : "RELEASED" 
9  }, 
10  { 
11    "group_id" : 392873, 
12    "status" : "RELEASED" 
13  } 
14]

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.

Listing 5.9: Return Value Example
1{ 
2  "version": 1234 
3}

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.


Verb Resource

Description




GET /folder

Get all folders for the authenticated identity

POST /folder

Create a new folder

GET /folder/:id

Get a given folder

POST /folder/:id

Update a given folder

DELETE /folder/:id

Delete a given folder

POST /folder/:id/purge

Deletes everything below a folder

POST /folder/:id/move_to_trash

Move a given folder to user’s trashcan

GET /folder/:id/download

Download a given folder


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)

Listing 6.1: Folder List Example
42[ 
43  { 
44    "created" : "2013-01-06 13:37:18", 
45    "company_id" : 147903, 
46    "parent" : null, 
47    "name" : "My first folder", 
48    "id" : 155111, 
49    "permissions" : { "groups" : ["READ"] } 
50  }, 
51  { 
52    "created" : "2013-01-08 12:33:15", 
53    "company_id" : 147903, 
54    "parent" : 155111, 
55    "name" : "My folder", 
56    "id" : 202531, 
57    "permissions" : { "groups" : ["READ", "WRITE", "ADMIN"] } 
58  } 
59]

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

Listing 6.2: Payload Example
60{ 
61  "company_id" : 147903, 
62  "parent" : 155111, 
63  "name" : "My newly created folder", 
64}

6.2.2 Return Value

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

Listing 6.3: Return Value Example
65{ 
66  "created" : "2014-06-26 14:11:25", 
67  "company_id" : 147903, 
68  "parent" : 155111, 
69  "name" : "My newly created folder", 
70  "id" : 392913 
71}

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

Listing 6.4: Folder Example
72{ 
73  "created" : "2014-06-26 14:11:25", 
74  "company_id" : 147903, 
75  "parent" : 161503, 
76  "name" : "test gladiiiiii", 
77  "id" : 196951 
78}

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

Listing 6.5: Payload Example
79{ 
80  "company_id" : 147903, 
81  "parent" : 155111, 
82  "name" : "My updated folder", 
83}

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

Listing 6.6: Updated Folder Example
84{ 
85  "created" : "2014-06-26 145:11:25", 
86  "company_id" : 147903, 
87  "parent" : 155111, 
88  "name" : "My updated folder", 
89  "id" : 196951 
90}

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:


Flag

Description



READ

User can see the folder

ADMIN

User can change the folder

WRITE

User can upload to the folder

PERMANENT

The folder is permanent (cannot be altered or deleted)

TRASH

The folder is the user’s trashcan (implies PERMANENT)

PUBLIC

The folder is a public folder (implies PERMANENT)


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.


Verb Resource

Description




POST /clique

Create a new clique

GET /clique

Get the cliques I can manage

POST /clique/:id

Update a clique

DELETE /clique/:id

Delete a clique

GET /clique/:id/member

Get a list of users in the clique

POST /clique/:id/member/:user_id

Put a user in a clique

DELETE /clique/:id/member/:user_id

Remove a user from a clique

GET /clique/:id/folder

Get a list of folders in the clique

POST /clique/:id/folder/:user_id

Put a folder in a clique

DELETE /clique/:id/folder/:user_id

Remove a folder from a clique


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.

Listing 7.1: Clique-created Example
91{ 
92   "id" : 53, 
93   "name": "The it crowd", 
94   "skyfish_id": 102 
95}

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.

Listing 7.2: Clique List Example
96[ 
97   { 
98      "id" : 53, 
99      "name": "The it crowd", 
100      "skyfish_id": 102, 
101      "thumbnail_id": null 
102   } 
103]

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.

Listing 7.3: Clique User Member List Example
104[ 
105   { 
106      "id" : 53, 
107      "user_id": 333, 
108      "clique_id": 102 
109   } 
110]

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.

Listing 7.4: Clique to User Member Example
111{ 
112   "id" : 53, 
113   "user_id": 333, 
114   "clique_id": 102 
115}

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.

Listing 7.5: Clique Folder Member List Example
1[ 
2   { 
3       "folder_id": 333, 
4       "clique_id": 102, 
5       "permissions": ["READ"] 
6   } 
7]

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.

Listing 7.6: Clique Folder Member Example
1{ 
2   "folder_id": 333, 
3   "clique_id": 102, 
4   "permissions": ["READ"] 
5}

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.


Verb Resource

Description




GET /media/:id/download_location

Download the location for a media file

GET /media/:id/download_location/:size

Download the location for a media file with a given size

POST /folder/:id/zip-file

Download the location of a folder in ZIP format


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.

CBX-HMAC Key=mykey HMAC=84b252e61bd800f33fcd58fb006a0f01377ec979 TS=1383307501

Then base64 encodes the authorization information above.

base64_encode ( CBX-HMAC Key=mykey HMAC=84b252e61bd800f33fcd58fb006a0f01377ec979 TS=1383307501) = Q0JYLUhNQUMgS2V5PW15a2V5IEhNQUM9ODRiMjUyZTYxYmQ4MDBmMzNmY2Q1OGZiMDA2YTBmMDEzNzdlYzk3OSBUUz0xMzgzMzA3NTAx

Finally the authorized URL looks like this.

https://api.colourbox.com/media/123456789/download_location?Authorization=Q0JYLUhNQUMgS2V5PW15a2V5IEhNQUM9ODRiMjUyZTYxYmQ4MDBmMzNmY2Q1OGZiMDA2YTBmMDEzNzdlYzk3OSBUUz0xMzgzMzA3NTAx

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

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.

Listing 9.1: Response example
1{ 
2    "media_id":456756 
3}

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


Verb Resource

Description




POST /upload/register

Register the download


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.

Listing 9.2: Payload example
1{ 
2  "folder": 1337, 
3  "redirectURL": "http://www.myservice.com/upload-done" 
4}

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.

Listing 9.3: Response Example (some values truncated for readability)
1{ 
2   "action" : "https://colourbox-upload.s3-eu-west-1.amazonaws.com", 
3   "enctype" : "multipart/form-data", 
4   "method" : "POST", 
5   "fields" : [ 
6      { 
7         "name" : "success_action_redirect", 
8         "value" : "http://api.colourbox.com/upload/done?redirect=http%3A%2F%2Fwww.myservice.com%2Fupload-done", 
9         "type" : "hidden" 
10      }, 
11      { 
12         "type" : "hidden", 
13         "value" : "upload/777/33/${filename}", 
14         "name" : "key" 
15      }, 
16      { 
17         "value" : "REDUCED_REDUNDANCY", 
18         "type" : "hidden", 
19         "name" : "X-Amz-Storage-Class" 
20      }, 
21      { 
22         "value" : "AKIAJFHN67ZGNWA...", 
23         "type" : "hidden", 
24         "name" : "X-Amz-Credential" 
25      }, 
26      { 
27         "name" : "X-Amz-Algorithm", 
28         "type" : "hidden", 
29         "value" : "AWS4-HMAC-SHA256" 
30      }, 
31      { 
32         "value" : "20170601T080641Z", 
33         "type" : "hidden", 
34         "name" : "X-Amz-Date" 
35      }, 
36      { 
37         "type" : "hidden", 
38         "value" : "eyJleHBpcmF0aW9uI...", 
39         "name" : "Policy" 
40      }, 
41      { 
42         "name" : "X-Amz-Signature", 
43         "value" : "cb56a851d7321e8fa90f...", 
44         "type" : "hidden" 
45      }, 
46      { 
47         "type" : "file", 
48         "name" : "file" 
49      } 
50   ] 
51}

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.


Verb Resource

Description




GET /company/:id/users

Company users

GET /company/:id/folders

Company folders

GET /company/:id/apikeys

Company API key/secret


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.

Listing 10.1: Response Example
1[ 
2  { 
3    "id": 245942, 
4    "fullname": "Nora Malkeko", 
5    "href": "https://api.colourbox.com/user/245942" 
6  }, 
7  { 
8    "id": 233496, 
9    "fullname": "Bedstemor And", 
10    "href": "https://api.colourbox.com/user/233496" 
11  } 
12]

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.

Listing 10.2: Response Example
1[ 
2  { 
3    "id": 56, 
4    "key": "notverysecretkey", 
5    "secret": "verysecretsecret", 
6    "companyId": 42 
7  } 
8]

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.

Listing 10.3: Response Example
1{ 
2    "protocol" : "https", 
3    "host" : "api.colourbox.com" 
4}

Chapter 11
User

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


Verb Resource

Description




GET /user/:id/folders

User folders

GET /user/:id/profileimage

User profile image

GET /user/:id/clique

Get the cliques for a user

POST /user/:id/profileimage

Upload new user profile image


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

Listing 11.1: Response example
1[ 
2  { 
3    "id": "1337", 
4    "name": "My first folder", 
5    "parent": null, 
6    "company_id": "42", 
7    "created": "2013-05-21 13:46:39", 
8    "permissions": { 
9      "groups": [ 
10        "ADMIN", 
11        "READ", 
12        "WRITE" 
13      ] 
14    } 
15  }, 
16  { 
17    "id": "777", 
18    "name": "Second folder", 
19    "parent": "1337", 
20    "company_id": "42", 
21    "created": "2013-05-21 13:54:32", 
22    "permissions": { 
23      "groups": [ 
24        "READ" 
25      ] 
26    } 
27  } 
28]

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.

Listing 11.2: Response example
1[ 
2   { 
3      "id" : 1062, 
4      "name" : "A clique", 
5      "skyfish_id" : 2439, 
6      "thumbnail_id" : null 
7   } 
8]

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.


Verb Resource

Description




GET /user/:id/diskusage

The users disk usage

GET /company/:id/diskusage

The companys disk usage


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

Listing 12.1: Response example
1[ 
2    { 
3        "company_id" : 147906, 
4        "diskusage" : 3014034425 
5    }, 
6    { 
7        "company_id" : 194375, 
8        "diskusage" : 15438486 
9    } 
10]

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

Listing 12.2: Response example
1{ 
2    "used" : 3018034425, 
3    "max" : 5368709120 
4}

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


Verb Resource

Description




POST /signup

Signup for a new free Skyfish


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.

Listing 13.1: Examples of RFC 5646 language tags
1da-DK 
2de-DE 
3en-US 
4en-EN

13.1.2 References

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

Listing 13.2: Newly created Skyfish example
1{ 
2  "company": { 
3    "id": 5454, 
4    "href": "https://api.colourbox.com/company/5454" 
5  }, 
6  "user": { 
7    "id": 8989, 
8    "href": "https://api.colourbox.com/user/8989" 
9  } 
10}

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.


Verb Resource

Description




GET /media/:id

Get media document

GET /media/:id/download_location

Download the media

GET /media/:id/download_location/:size

Download a preview of the media with :size

GET /search/colourbox/download

Lets you search in your 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

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

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.