Face Recognition API Documentation

Getting Started

The Eagle Vision API lets you enroll identities and recognize faces in uploaded images. All requests are made over HTTPS to the base URL below. Every request must include your Authorization header with a valid client token.

Base URL

http://81.17.99.81:8000

Content Type

multipart/form-data

for all file-upload endpoints

Your client token is provisioned automatically when you register. Find it on your Dashboard or Billing page.

Authentication

Every API call must include a Bearer token in the HTTP Authorization header. Tokens are prefixed with frapi_.

http

Authorization: Bearer frapi_your_client_token_here

Security: Never expose your client token in client-side JavaScript, mobile app source code, or public repositories. Always proxy API calls through your backend.

Rate Limits

Rate limits are enforced per client token. If you exceed your limit you will receive a 429 Too Many Requests response. Retry after the number of seconds indicated in the Retry-After header.

Plan	Requests / min	Burst	Points / month
Starter	30	60	1,000
Growth	100	200	3,000
Business	500	1,000	7,500
Enterprise	Custom	Custom	Unlimited

POST /faces/enroll 1 point / call

Enroll Face

Registers a new face identity in the system. Submit a multipart/form-data request with a clear face photo and identity metadata. One API point is deducted per successful enrollment.

Request Parameters

Field	Type	Required	Description
`image`	file	required	JPG, PNG, BMP, or WebP — clear single face photo
`person_name`	string	required	Full display name for the identity
`person_id`	string	optional	Your internal identifier (employee ID, UUID, etc.)
`metadata`	string	optional	JSON string for any additional attributes to store

Code Examples

curl -X POST http://81.17.99.81:8000/faces/enroll \
  -H "Authorization: Bearer frapi_your_token" \
  -F "image=@photo.jpg" \
  -F "person_name=Jane Doe" \
  -F "person_id=EMP-001"

POST /faces/recognize 1 point / call

Recognize Face

Identifies a person from an uploaded photo against all enrolled identities in your collection. Returns ranked candidates with similarity scores. Only candidates above the threshold are returned.

Request Parameters

Field	Type	Default	Description
`image`	file	—	Photo to identify (JPG, PNG, BMP, WebP)
`top_k`	int	5	Max number of candidates to return (1–20)
`threshold`	float	0.65	Minimum similarity score 0.0–1.0. Higher = stricter match

Code Examples

curl -X POST http://81.17.99.81:8000/faces/recognize \
  -H "Authorization: Bearer frapi_your_token" \
  -F "image=@query.jpg" \
  -F "top_k=5" \
  -F "threshold=0.65"

GET /faces

List Faces

Returns a paginated list of all enrolled identities belonging to your client token. Use limit and offset for pagination. This endpoint does not consume API points.

Query Parameters

Parameter	Type	Default	Description
`limit`	int	100	Max records per page (1–500)
`offset`	int	0	Number of records to skip

Code Examples

curl -X GET "http://81.17.99.81:8000/faces?limit=100&offset=0" \
  -H "Authorization: Bearer frapi_your_token"

DELETE /faces/{face_id}

Delete Face

Permanently removes an enrolled identity from the system by its numeric face ID. This action is irreversible — the face will need to be re-enrolled to restore it. Does not consume API points.

Path Parameters

Parameter	Type	Description
`face_id`	int	The numeric ID of the enrolled face to delete

Code Examples

curl -X DELETE http://81.17.99.81:8000/faces/42 \
  -H "Authorization: Bearer frapi_your_token"

Error Codes

The API uses standard HTTP status codes. All error responses include a JSON body with a detail field describing the issue.

Code	Status	Meaning
200	OK	Request completed successfully.
400	Bad Request	No face detected in the image, or the image format is not supported. Ensure a clear, well-lit, forward-facing photo.
401	Unauthorized	Missing or invalid client token. Verify your `Authorization` header.
402	Payment Required	Insufficient API points. Top up your account on the Billing page to continue.
403	Forbidden	Admin tokens cannot access client endpoints. Use a provisioned client token instead.
404	Not Found	The requested face ID does not exist or belongs to a different client token.
429	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header for when to retry.
422	Unprocessable Entity	Request structure is valid but contains invalid field values (e.g., missing required field).
500	Internal Server Error	Unexpected server-side failure. Contact support if the issue persists.

SDKs & Libraries

All API endpoints are plain HTTP — no SDK required. Use any HTTP library in any language. Below are the recommended packages for each platform shown in the code examples.

JS

JavaScript / Node.js

node-fetch / fetch (built-in)

No install needed — use native fetch

C#

C# / .NET

System.Net.Http.HttpClient

Built into .NET — no extra package

Py

Python

requests

pip install requests

Fl

Flutter / Dart

http

flutter pub add http

Need a native SDK or custom integration?

Contact our team — we offer enterprise integration support.

Contact Support