REST API Reference

Base URL: http://localhost:8080 (default)

Biometric operation endpoints (/api/v1/search, /api/v1/verify, /api/v1/enrol, /api/v1/delete) accept multipart/form-data with an image file part and a metadata JSON part, and return XML responses. Utility endpoints return JSON.

POST /api/v1/search

1:N face search. Runs the probe image through the full pipeline (detection → alignment → PAD → quality → extraction) and searches the FAISS index for the closest matches.

Request (multipart/form-data)

Part	Type	Required	Description
`image`	file	yes	JPEG or PNG face image
`metadata`	JSON string	no	Search parameters (see below)

curl -X POST http://localhost:8080/api/v1/search \
  -F image=@probe.jpg \
  -F 'metadata={"partition":"default","top_k":5,"threshold":0.4}'

Metadata fields

Field	Type	Default	Description
`partition`	string	`"default"`	Gallery partition to search
`top_k`	integer	`5`	Maximum candidates to return
`threshold`	float	`0.45`	Minimum similarity score (0–1)

Response (XML)

<SearchResponse>
  <status>OK</status>
  <candidates>
    <candidate>
      <subject_id>person-001</subject_id>
      <score>0.823</score>
      <rank>1</rank>
    </candidate>
    <candidate>
      <subject_id>person-042</subject_id>
      <score>0.611</score>
      <rank>2</rank>
    </candidate>
  </candidates>
  <quality_score>0.87</quality_score>
  <model_id>arcface-w600k-r50</model_id>
</SearchResponse>

Error responses

HTTP status	Reason
400	No face detected, or image failed to decode
422	Quality gate rejected the image (score below threshold)
451	PAD gate rejected the image (spoof detected)

POST /api/v1/verify

1:1 verification. Compares the probe image against a specific enrolled subject.

Request (multipart/form-data)

curl -X POST http://localhost:8080/api/v1/verify \
  -F image=@probe.jpg \
  -F 'metadata={"subject_id":"person-001","partition":"default"}'

Metadata fields

Field	Type	Required	Description
`subject_id`	string	yes	Subject to verify against
`partition`	string	no	Gallery partition (default: `"default"`)
`threshold`	float	no	Match threshold (default: `0.45`)

Response (XML)

<VerifyResponse>
  <status>OK</status>
  <match>true</match>
  <score>0.823</score>
  <subject_id>person-001</subject_id>
  <quality_score>0.87</quality_score>
  <model_id>arcface-w600k-r50</model_id>
</VerifyResponse>

POST /api/v1/enrol

Enrol a new face into the gallery. Runs detection → alignment → PAD → MAD → quality → extraction, then stores the 512-dim template.

Request (multipart/form-data)

curl -X POST http://localhost:8080/api/v1/enrol \
  -F image=@photo.jpg \
  -F 'metadata={"subject_id":"person-001","partition":"default"}'

Metadata fields

Field	Type	Required	Description
`subject_id`	string	yes	Unique identifier for this subject
`partition`	string	no	Gallery partition (default: `"default"`)

Response (XML)

<EnrolResponse>
  <status>OK</status>
  <subject_id>person-001</subject_id>
  <quality_score>0.91</quality_score>
  <model_id>arcface-w600k-r50</model_id>
</EnrolResponse>

POST /api/v1/delete

Remove a subject’s template from the gallery. No image required.

Request (application/json)

curl -X POST http://localhost:8080/api/v1/delete \
  -H 'Content-Type: application/json' \
  -d '{"subject_id":"person-001","partition":"default"}'

Response (XML)

<DeleteResponse>
  <status>OK</status>
  <subject_id>person-001</subject_id>
</DeleteResponse>

GET /health

Returns the health status of all system components.

Response (JSON)

{
  "status": "healthy",
  "components": {
    "faiss_index": true,
    "onnx_detection": true,
    "onnx_recognition": true,
    "onnx_quality": true,
    "onnx_pad": true
  }
}

Returns HTTP 503 if any component is unhealthy.

GET /api/v1/partitions

List available gallery partitions.

Response (JSON)

{
  "partitions": ["default", "watchlist", "employees"]
}

GET /api/v1/gallery

Return gallery statistics.

Response (JSON)

{
  "total_subjects": 1423,
  "partitions": {
    "default": 1200,
    "watchlist": 223
  }
}