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 /generateAuthToken only issues a token to a verified email + phone pair. On v1 /generateAuthToken issues a token directly with no verification. Endpoints marked v2 return 404 when called on v1.
Authentication
Every endpoint except /new-credentials, /authenticate-credentials and /generateAuthToken requires a client token. (/authTokens, /deleteAuthToken and /stats are token-authenticated — they act on the account that owns the token you present.) Send the token in the X-Auth-Token request header (it may also be supplied as an auth_token form field).
Optionally, restrict where a token may be used with a source allow-list. By default every source is permitted. Add one or more identifiers via /whitelist-identifier (an IP address, or a server id sent as the X-Server-Id header) and from then on authenticated calls are accepted only from a listed source — anything else is rejected with HTTP 403.
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/generateAuthToken to obtain a client token. You can issue several — each with its own name — and list or remove them with /authTokens and /deleteAuthToken. (On v1 you can skip straight to /v1/generateAuthToken.)
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.