Overview
All requests are POST. The base URL is https://api.facenition.com; each endpoint is reached at https://api.facenition.com/<endpoint>.
Versioning
Any endpoint may be prefixed with a version segment: https://api.facenition.com/v1/<endpoint> or https://api.facenition.com/v2/<endpoint>. An unversioned path defaults to v1. The version may also be set with an X-API-Version header (e.g. X-API-Version: 2), which overrides any prefix.
Most endpoints behave identically across versions. The differences are: v2 adds /new-credentials and /authenticate-credentials (marked v2 below), and on v2 /generateToken only issues a token to a verified email + phone pair. On v1 /generateToken issues a token directly with no verification. Endpoints marked v2 return 404 when called on v1.
Authentication
Every endpoint except /new-credentials, /authenticate-credentials, /generateToken and /token requires a client token. Send it in the X-Auth-Token request header (it may also be supplied as an auth_token form field).
Getting a token (v2)
On v2, tokens are only issued to verified pairs. First call /v2/new-credentials to receive a one-time code by email and another by SMS, then submit both to /v2/authenticate-credentials. Once verified, call /v2/generateToken to obtain the client token. (On v1 you can skip straight to /v1/generateToken.)
Sending images
Image fields accept a file upload via multipart/form-data (recommended). To send several images, repeat the same field name once per image. Image fields also accept a base64-encoded string supplied in an application/json body.
Accuracy
Several endpoints take an accuracy parameter — an integer from 1 to 8 (default 4) that controls matching tolerance. For verification, the same accuracy used at /generate must be supplied at /authenticate.
Errors
On failure a response returns { "ok": false, "error": "<message>" } with an appropriate HTTP status — 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 410 gone, 429 too many requests, or 502 upstream error.