REST API Reference

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

Biometric operation endpoints (/api/v1/search, /api/v1/verify, /api/v1/enrol, /api/v1/delete) 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 → quality → extraction) and searches the FAISS index for the closest matches.

Request

{
  "image": "<base64-encoded JPEG or PNG>",
  "partition": "default",
  "top_k": 5,
  "min_score": 0.4
}

Field	Type	Required	Description
image	string	yes	Base64-encoded face image
partition	string	no	Gallery partition to search (default: "default")
top_k	integer	no	Maximum candidates to return (default: 5)
min_score	float	no	Minimum similarity score threshold (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)
422	MAD gate rejected the image (morphing detected, enrol path only)

---

POST /api/v1/verify

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

Request

{
  "image": "<base64-encoded JPEG or PNG>",
  "subject_id": "person-001",
  "partition": "default"
}

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 in the FAISS index.

Request

{
  "image": "<base64-encoded JPEG or PNG>",
  "subject_id": "person-001",
  "partition": "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>

Note

Raw imagery is never persisted. Only the 512-dim float32 embedding is stored.

---

POST /api/v1/delete

Remove a subject’s template from the gallery. Bypasses the image pipeline — no image required.

Request

{
  "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
  }
}