Getting started

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

Before you begin

• An agreement with Colourbox. 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.
• An API key and secret. You find them on your API keys page.
• curl or equivalent software capable of doing HTTP requests.

The API key

The API key uniquely identifies the application that is used to access the Skyfish API. Each application must use its own API key and secret. The 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 combination with user credentials.

Caution

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

Your first requests

1. Compute an HMAC

   The user who is going to use the API logs in. You POST the username and password together with the API key, a UNIX timestamp and an HMAC to /authenticate/userpasshmac. The HMAC is computed like this:

   HEX(HMAC-SHA1(secret, apikey + ":" + ts))

   PHP

   $ts = time();
   $hmac = hash_hmac('sha1', "$apikey:$ts", $secret);

   Node.js

   import { createHmac } from 'node:crypto';
   
   const ts = Math.floor(Date.now() / 1000);
   const hmac = createHmac('sha1', secret).update(`${apikey}:${ts}`).digest('hex');

   Shell

   TS=$(date +%s)
   HMAC=$(printf '%s' "$APIKEY:$TS" | openssl dgst -sha1 -hmac "$SECRET" | awk '{print $2}')

   With the API key company2key, the secret company2secret and the timestamp 1429187979, the HMAC is 7e42196943a343e7494fc2636a3f7313edfcd81f.

2. Get an auth-token

   Send your own username, password and API key with the timestamp and HMAC you just computed. The example values below are only there to show the format: the timestamp must be within 60 seconds of the server’s clock, so the request is refused if you send it as it is.

   curl -d '{"username":"ausername","password":"verysecret","key":"company2key","ts":1429187979,"hmac":"7e42196943a343e7494fc2636a3f7313edfcd81f"}' \
     https://api.colourbox.com/authenticate/userpasshmac

   This returns status code 200 and a JSON document:

   {
     "validUntil": 1430397579,
     "type": 1,
     "ownerIdentifier": 645654,
     "token": "0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b"
   }

   Use the token on all subsequent calls. A token is very similar to the “session” concept from regular web development and has a default lifetime of 14 days.

3. Search for images

   Send the token in the Authorization header:

   Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b

   Search for kittens with q, ask for 10 results with media_count, and choose what you want back with return_values – here a thumbnail URL, the unique media ID and the title:

   curl -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"

   The result has two parts. The media found is in response.media – pictures, vectors or video. The rest is statistics: hits is how many results were found in all, media_count how many were returned and media_offset the offset into the full result, which you can use for pagination. See Search for all options.

4. Limit the search to a folder

   By default a search covers all folders owned by the user. Limit it with folder_ids:

   curl -H "Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b" \
     "https://api.colourbox.com/search?q=kitten&media_count=10&return_values=thumbnail_url&folder_ids=42"

   List the folders the company has access to with /folder:

   curl -H "Authorization: CBX-SIMPLE-TOKEN Token=0fe6cb5476f448f78f6ee5cf259f0184a40e9c4b" \
     https://api.colourbox.com/folder

   [
     { "company_id": 1995, "parent": null, "name": "My first folder", "id": 42 },
     { "company_id": 1995, "parent": null, "name": "Pictures", "id": 1337 }
   ]

   More about a single folder is at /folder/:id.

How the API works

Resources and verbs

A resource is a URL endpoint, e.g. /search. Resources usually refer to an object that can be retrieved and/or modified, e.g. /media/35 or /user/1337. Some resources are not “true” resources: /search cannot be retrieved and modified in the normal sense. All resources are prefixed with the base URL https://api.colourbox.com, which we omit in the rest of the documentation.

The HTTP verb defines the action. A GET to /media/43 returns a document representing the resource; a POST to /user/56 modifies the user. The API uses GET, POST and DELETE – not all verbs are supported on all resources.

Response codes and responses

The overall status of a request is conveyed via HTTP status codes. Check the status code before making assumptions about the body: 2xx means everything went fine, 4xx that the request could not be processed due to a user error, and 5xx that it could not be processed due to a server error.

The response body, if present, is JSON.

Note

We reserve the right to extend the returned response content in order to keep providing needed functionality. Existing content will not be modified for backwards compatibility reasons – a new version of the API will be issued in that case. Make sure your use of the responses is resilient to additions.