Overview

Endpoint

All REST API requests should be sent to https://api.findface.pro/v0/. HTTPS is required. HTTP (without SSL) is disabled to protect your privacy and your access token.

API Versions

The API version is increased every time a major change is made and allows us to avoid breaking backwards compatibility. The API version should be specified in the request path (for example v0 in /v0/detect/). The most recent version in v1. When starting new project, you should always use the latest version of the API.

Authentication

All API methods require a simple token-based HTTP Authentication. In order to authenticate, you should put world "Token" and a key into the Authorization HTTP header, separated by a whitespace:

Authorization: Token yfT8ftheVqnDLS3Q0yCiTH3E8YY_cm4p

All requests that fail to provide a valid authentication token will result in a HTTP 401 Unauthorized response. You can get your token after signing up to FindFace Cloud API or logging in into your FindFace Account. If you believe that your authorization token might have been compromised, please contact us immediately.

Parameters Format

There are three ways to pass parameters to the API methods:
  • application/json: parameters are represented by a JSON contained in the body.
  • application/x-www-form-urlencoded: parameters are represented by form field names and values.
  • multipart/form-data: parameters are encoded into separate parts. This way supports uploading a photo image file in the same request.
  • query string: parameters are appended to request URI. When passing parameters in a query string, complex structures (such as bboxes) should be encoded in JSON.
There are two ways of specifying a photo image file:
  • As a publicly accessible URL.
  • Included in a request as part of multipart form (see example for /identify/ later in the documentation).

All responses are in JSON format and UTF-8 encoding.

Using Examples

Examples in methods descriptions illustrate possible method request and its response. To check the examples without writing a code, we recommend using Advanced REST Client or similar tool and entering request parameters though their GUI.

Please note that you may need to change Token to a valid Token issued to you.