The API will always return a JSON response (even for errors). Each request should consist of the desired API method, any parameters, your unique API key and a request hash.

Although all curriculum elements are versioned, only 'approved' versions are available via this API. The unique identifier included with query results is tied to the entire history of a given object, rather than a specific version. This means that an object ID will always stay the same, regardless of any changes or new versions.


Our API requires that your API key be included in each request, as well as an HMAC-SHA1 hash. This hash is generated from the method path and query string, using your API secret as the key.

The following rules apply:

A hash generator is included in the playground.

Example request:

API Key b1215747-ab55-4d83-8b49-9f072f085683
API Secret d4bea8034b51
Method to call /api/query/123?date=today
...add API key /api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683
...hash using secret 404085eb7c45ced17705b9b77d4fb95c8e480f60
...append as parameter /api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683&hash=404085eb7c45ced17705b9b77d4fb95c8e480f60
...add host

Show example code


// Method with API key string query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret string secret = "d4bea8034b51"; // Hash byte[] queryBytes = Encoding.ASCII.GetBytes(query); byte[] secretBytes = Encoding.ASCII.GetBytes(secret); byte[] hashBytes = (new HMACSHA1(secretBytes)).ComputeHash(queryBytes); string hash = BitConverter.ToString(hashBytes).Replace("-", "").ToLower(); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"


// NB Example uses Apache Commons Codec import org.apache.commons.codec.digest.HmacUtils; // Method with API key String query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret String secret = "d4bea8034b51"; // Hash String hash = HmacUtils.hmacSha1Hex(secret.getBytes(), query.getBytes()); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"


// NB Example uses CryptoJS // Method with API key var query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret var secret = "d4bea8034b51"; // Hash var hash = CryptoJS.HmacSHA1(query, secret).toString(); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"


// Method with API key $query = '/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683'; // API secret $secret = 'd4bea8034b51'; // Hash $hash = hash_hmac('sha1', $query, $secret); // $hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"


Our API uses conventional HTTP response codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error resulting from the provided information (e.g. a required parameter was missing, an incorrect key/hash) and codes in the 5xx range indicate an error on our server.

See the object definition for more details.