Skip to main content
POST
/
api
/
agent
/
face
Face Search
curl --request POST \
  --url https://encrata.com/api/agent/face \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_url": "<string>",
  "threshold": 123
}
'
{
  "image_url": "https://example.com/photo.jpg",
  "matched": true,
  "threshold": 0.8,
  "faces_detected": 1,
  "matches": [
    {
      "uuid": "9f1c2a4e-7b3d-4f6a-9c8e-1d2f3a4b5c6d",
      "name": "John Doe",
      "probability": 0.97,
      "left": 142,
      "top": 88,
      "right": 310,
      "bottom": 256
    }
  ],
  "credits": 5,
  "latency_ms": 920
}

​
Authentication

Requires an API key in the Authorization header. 
Authorization: Bearer YOUR_API_KEY

​
Request

​
image_url
string
required
Publicly accessible URL of the probe image. JPG, PNG, and WebP are supported.
​
threshold
number
Minimum match confidence between 0 and 1. Faces below this probability are excluded. Default: 0.8.

​
Response

Returns whether the face matched anyone on your watchlist, along with per-match confidence and face bounding boxes. 
{
  "image_url": "https://example.com/photo.jpg",
  "matched": true,
  "threshold": 0.8,
  "faces_detected": 1,
  "matches": [
    {
      "uuid": "9f1c2a4e-7b3d-4f6a-9c8e-1d2f3a4b5c6d",
      "name": "John Doe",
      "probability": 0.97,
      "left": 142,
      "top": 88,
      "right": 310,
      "bottom": 256
    }
  ],
  "credits": 5,
  "latency_ms": 920
}

​
Credits

5 credits per search. Failed searches are automatically refunded.

​
Watchlist

Face search matches against your private watchlist. Manage it from the dashboard:
  • Enroll — Add a person with a name and reference photo
  • Rename / remove — Update or delete enrolled persons at any time
Photos are converted to face templates; original images are not stored.