Update Guide Version 2.2 to 2.3

Version 2.3 of the Retina API sees improvements to the algorithm behind the /text endpoint.

Fingerprints returned by the /text endpoint are now generally sparser with a maximum sparsity of 6% (formerly the maximum sparsity was 12%). In addition to the /text endpoint, this change may affect all endpoints which are dependent on the /text endpoint, such as the following:

  • /text/keywords
  • /text/slicing
  • /classify/createCategoryFilter

And of course, any use of the /compare or /expressions endpoints which involve the /text endpoint. Note that a Fingerprint created for a document or text using the older algorithm (v. 2.2), while it will not be exactly the same, will still be very similar to a Fingerprint created for the same document or text using the newer 2.3 version of the algorithm.

In contrast to the Retina API, Fingerprints produced via the Retina-Spark API are now more dense (previously these had a maximum sparsity of 2%).

Update Guide Version 2.1 to 2.2

Main Changes Overview

Our API has undergone several improvements and changes. The main changes from version 2.1 are:

  • Under the hood
  • NEW /text/detect_language endpoint in the Text API tab.
  • NEW /compare/bulk endpoint in the Compare API tab.
  • NEW /classify/create_category_filter endpoint.
  • NEW Configurable Swagger user interface
  • NEW the Retina API is now available on the Microsoft Azure Marketplace.

Changes under the Hood

New changes under the hood now result in:

  • Speed improvements on all text related endpoints
  • Speed improvements on all similar_terms endpoints
  • Speed improvements on all context endpoints

NEW /text/detect_language endpoint

There is now a new /text/detect_language endpoint capable of detecting 50 languages. See our interactive API documentation for more details.

NEW /compare/bulk endpoint

There is now a new /compare/bulk endpoint, enabling multiple comparisons to be made simultaneously. See our interactive API documentation for more details.

NEW /classify/create_category_filter endpoint

We now provide a /classify/create_category_filter endpoint allowing users to easily create a category filter for a classification system. For more information see the Classification section and our interactive API documentation.

NEW configurable Swagger UI

Users of Amazon Machine Instance versions of the Retina API can now enable/disable their Swagger user interface as and when required (via the script’s setup command). See the Amazon Web Services market place and our AWS Documentation for more information on using the Retina API with an Amazon Machine Instance.

NEW Microsoft Azure Marketplace

The Retina API is now available on Microsoft’s Azure Marketplace.

Update Guide Version 1.x to 2.x

Main Changes Overview

Our API has undergone several improvements and changes. The main changes from version 1 are:

  • Under the hood
  • Changes to the Swagger UI interactive API
  • Changes to api-key usage
  • Returned objects have changed
  • Some endpoints no longer exist
  • Some parameters no longer exist
  • Changes to parameter and endpoint naming
  • NEW Fingerprint option
  • NEW bulk operation endpoints
  • NEW image endpoints (including bulk)

Under the Hood

The relevant changes under the hood are:

  • Faster and more accurate keyword endpoint
  • Faster and more accurate text to fingerprint transformation
  • Generally faster REST backend

Changes to Swagger UI interactive API

If you’re using our interactive API you will immediately see that the user interface has changed to an overview page with a menu bar. Each menu item on the menu bar displays the endpoints for a particular (sub) api in a frame below the menu bar.

Changes to API key usage

Up to Version 2.2.0 Due to security reasons, the mode of supplying your api-key has changed. You can still use the same api-key that was issued to you. The key now has to be supplied as a HTTP-Header with the new name api-key. (Beware: this new name uses a dash - whereas the former name of the parameter api_key used an underscore character ). It is no longer possible to supply the key as a Query parameter.

Returned objects have changed

The objects returned by our API now have a modified structure. For instance, the Term object now has the form:

Term {
  fingerprint (Fingerprint, optional): The Fingerprint of this term.,
  df (number, optional): The df value of this term.,
  term (string, optional): The term as a string.,
  pos_types (array[string], optional): The pos types of the term.,
  score (number, optional): The score of this term.

Please see the individual endpoints of our interactive API documentation for full details of all returned objects.

Some Endpoints no longer exist

The specialized API endpoints for operations on Fingerprints no longer exist. Please note that Fingerprints can be obtained by setting the get_fingerprint parameter on the relevant endpoints.

Some Parameters no longer exist

The returnType parameter no longer exists. Users requiring an Image return type should now use the new Image API.

The plotShape parameter has been removed from all Text, Term, Compare and Expressions endpoints (because these endpoints no longer return images).

The imageScalar parameter has been removed from the Compare API (because this endpoint no longer returns images).

Changes to parameter and endpoint naming

Please be aware that names of endpoints and parameters have changed from camelCase to snake_case.

In particular, the /terms/similarTerms and /expressions/similarTerms endpoints are now /terms/similar_terms and /expressions/similar_terms respectively.

NEW Fingerprint option

You will notice that many endpoints now have a get_fingerprint parameter. Unless you specifically need a Fingerprint in the response object we recommend that you set this to the default value of false .


A new Image API has been added, collecting all image endpoints in one place for ease of use.

NEW bulk operation endpoints

In order to minimise network overhead for users, new bulk operation endpoints have been added to the following APIs:

  • Text API
  • Expressions API
  • Image API

Please see the relevant interactive API documentation for details.