F

Reference

API Reference

Base URL: https://api.facecore.dev. Authenticate requests using Authorization: Bearer <API_KEY>. Every response includes request_id.

GET/v1/healthPublic

Liveness probe returning process health and API version.

Request
curl https://api.facecore.dev/v1/health
200 OK Response
{
  "request_id": "req_01j9m2x9k1",
  "status": "ok",
  "version": "1.0.0"
}
GET/v1/readyPublic

Readiness probe verifying database connectivity and commercial model-license gates.

Request
curl https://api.facecore.dev/v1/ready
200 OK Response
{
  "request_id": "req_01j9m2x9k2",
  "ready": true,
  "database_ok": true,
  "commercial_gate_ok": true,
  "violations": []
}
GET/v1/modelsBearer API Key

List active detector, embedder, liveness, quality, and geometry models with license status.

Request
curl https://api.facecore.dev/v1/models \
  -H "Authorization: Bearer $FACECORE_KEY"
200 OK Response
{
  "request_id": "req_01j9m2x9k3",
  "models": [
    {
      "model_id": "arcface-r100-v1",
      "model_version": "1.2.0",
      "kind": "embedder",
      "license_id": "Apache-2.0",
      "commercial_ok": true,
      "status": "active",
      "capture_type": "selfie_id",
      "preprocessing_version": "pp-v1"
    }
  ]
}
POST/v1/detectBearer API Key

Detect faces, bounding boxes, 5-point landmarks, and optional quality metrics.

ParameterInTypeDescription
image*formfileJPEG, PNG, or WebP frame.
include_qualityformbooleanAttach quality score, pose_ypr, and reason codes (default true).
Request
curl https://api.facecore.dev/v1/detect \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F image=@frame.jpg \
  -F include_quality=true
200 OK Response
{
  "request_id": "req_01j9m2x9k4",
  "face_count": 1,
  "detector": "scrfd-2.5g",
  "faces": [
    {
      "bbox": [118.4, 84.0, 312.8, 344.2],
      "landmarks": [[178.1, 188.0], [254.6, 186.9], [216.2, 232.5], [184.5, 286.1], [249.8, 285.0]],
      "score": 0.994,
      "quality": {
        "score": 84.2,
        "reasons": [],
        "pose_ypr": [-3.8, 1.4, -0.7],
        "interocular_px": 76.5,
        "metrics": { "sharpness": 0.91, "brightness": 0.64 }
      }
    }
  ]
}
POST/v1/qualityBearer API Key

Evaluate blur, lighting, pose, occlusion, and interocular resolution before matching.

ParameterInTypeDescription
image*formfileImage containing a single face.
target_indexformintegerOptional face index when multiple faces are present.
Request
curl https://api.facecore.dev/v1/quality \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F image=@selfie.jpg
200 OK Response
{
  "request_id": "req_01j9m2x9k5",
  "face_count": 1,
  "quality": {
    "score": 84.2,
    "reasons": [],
    "pose_ypr": [-3.8, 1.4, -0.7],
    "interocular_px": 76.5,
    "metrics": { "sharpness": 0.91, "brightness": 0.64, "occlusion": 0.02 }
  }
}
POST/v1/verifyBearer API KeyIdempotent

1:1 face verification with quality gating, calibrated thresholds, optional liveness session binding, and full decision audit.

ParameterInTypeDescription
image_a*formfileLive capture or probe selfie.
image_b*formfileReference image or ID document crop.
profileformstringstrict | standard | relaxed (default standard).
capture_typeformstringselfie_selfie | selfie_id | multiview.
liveness_session_idformstringOptional completed one-time liveness session ID.
require_livenessformbooleanForce INCONCLUSIVE if liveness verdict is missing.
Idempotency-KeyheaderstringSafe retry key for 24-hour idempotent replay.
Request
curl https://api.facecore.dev/v1/verify \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -H "Idempotency-Key: 9b7c4e10-3a2d-4c8f-8e11-12f34a56b789" \
  -F image_a=@selfie.jpg \
  -F image_b=@id_photo.jpg \
  -F profile=standard \
  -F capture_type=selfie_id
200 OK Response
{
  "request_id": "req_01j9m2x9k6",
  "decision_id": "dec_01j9m2x9m0",
  "decision": "MATCH",
  "score": 0.614,
  "threshold": 0.452,
  "profile": "standard",
  "capture_type": "selfie_id",
  "quality": {
    "a": { "score": 84.2, "reasons": [], "pose_ypr": [-3.8, 1.4, -0.7], "interocular_px": 76.5, "metrics": {} },
    "b": { "score": 61.8, "reasons": [], "pose_ypr": [1.2, 0.4, 0.2], "interocular_px": 54.0, "metrics": {} }
  },
  "liveness": { "verdict": "LIVE", "score": 0.94, "tier": "active", "reasons": [] },
  "models": { "detector": "scrfd-2.5g", "embedder": "arcface-r100-v1@1.2.0" },
  "policy_version": "p-2026-01",
  "reasons": [],
  "geometry_source": "not_requested"
}
GET/v1/decisions/{decision_id}Bearer API Key

Retrieve the immutable audit record for a prior verification or identification decision.

ParameterInTypeDescription
decision_id*pathstringDecision ID returned by /v1/verify or /identify.
Request
curl https://api.facecore.dev/v1/decisions/dec_01j9m2x9m0 \
  -H "Authorization: Bearer $FACECORE_KEY"
200 OK Response
{
  "request_id": "req_01j9m2x9k7",
  "decision_id": "dec_01j9m2x9m0",
  "tenant_id": "tnt_01j9k4m8p2",
  "operation": "verify",
  "result": "MATCH",
  "score": 0.614,
  "threshold": 0.452,
  "profile": "standard",
  "reasons": [],
  "model_versions": { "detector": "scrfd-2.5g", "embedder": "arcface-r100-v1@1.2.0" },
  "policy_version": "p-2026-01",
  "latency_ms": 142,
  "decision_request_id": "req_01j9m2x9k6",
  "created_at": "2026-11-14T20:14:09Z"
}
POST/v1/liveness/sessionsBearer API Key

Issue a single-use, time-bounded liveness session with cryptographic nonce and randomized challenges.

ParameterInTypeDescription
tierbodystringpassive | active | multiview (default active).
challenge_countbodyintegerNumber of active head/blink prompts (default 2).
subject_idbodystringOptional subject identifier to bind the session.
Request
curl -X POST https://api.facecore.dev/v1/liveness/sessions \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "active", "challenge_count": 2}'
200 OK Response
{
  "request_id": "req_01j9m2x9k8",
  "session_id": "liv_01j9m2x9p1",
  "nonce": "n_84c19f0e2b7a",
  "challenges": ["turn_left", "blink"],
  "expires_at": "2026-11-14T20:19:09Z"
}
POST/v1/liveness/sessions/{session_id}/submitBearer API Key

Submit captured frames and signed HMAC-SHA256 capture manifest to close the one-time liveness session.

ParameterInTypeDescription
session_id*pathstringSession ID from /v1/liveness/sessions.
frames*formfile[]Ordered frame sequence.
manifest_signature*formstringHMAC-SHA256 signature over session_id, nonce, frame hashes, and timestamps.
Request
curl -X POST https://api.facecore.dev/v1/liveness/sessions/liv_01j9m2x9p1/submit \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F frames=@frame_1.jpg \
  -F frames=@frame_2.jpg \
  -F manifest_signature="$SIGNATURE"
200 OK Response
{
  "request_id": "req_01j9m2x9k9",
  "session_id": "liv_01j9m2x9p1",
  "verdict": "LIVE",
  "score": 0.942,
  "tier": "active",
  "reasons": []
}
POST/v1/multiview/analyzeBearer API Key

Verify left, centre, and right captures behave like a coherent 3D head rather than a tilted flat photo.

ParameterInTypeDescription
views*formfile[]Ordered left, centre, and right captures (3+ views).
reference_imageformfileOptional reference image to simultaneously run 1:1 verification.
Request
curl -X POST https://api.facecore.dev/v1/multiview/analyze \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F views=@left.jpg \
  -F views=@centre.jpg \
  -F views=@right.jpg
200 OK Response
{
  "request_id": "req_01j9m2x9ka",
  "passed": true,
  "multiview_score": 0.91,
  "checks": {
    "pose_progressive": true,
    "shape_consistent": true,
    "identity_consistent": true
  },
  "reasons": [],
  "geometry_source": "estimated_3d",
  "view_yaws": [-21.4, -1.2, 23.1]
}
POST/v1/consentsBearer API Key

Record explicit subject consent before enrolling a template into any gallery.

ParameterInTypeDescription
purpose*bodystringDeclared biometric processing purpose.
policy_versionbodystringPolicy version accepted by the user (default p-2026-01).
evidence_refbodystringOpaque reference to your signed consent artifact.
Request
curl -X POST https://api.facecore.dev/v1/consents \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "account_verification", "policy_version": "p-2026-01", "evidence_ref": "chk_4819"}'
200 OK Response
{
  "request_id": "req_01j9m2x9kb",
  "consent_id": "cns_01j9m2x9q4",
  "purpose": "account_verification",
  "policy_version": "p-2026-01",
  "granted_at": "2026-11-14T20:15:12Z"
}
POST/v1/galleriesBearer API Key

Create a tenant-isolated gallery with optional template retention limits.

ParameterInTypeDescription
name*bodystringHuman-readable gallery name.
purposebodystringPurpose label (default verification).
retention_daysbodyintegerOptional TTL in days (>= 1).
Request
curl -X POST https://api.facecore.dev/v1/galleries \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staff-access-lagos", "purpose": "verification", "retention_days": 365}'
200 OK Response
{
  "request_id": "req_01j9m2x9kc",
  "gallery_id": "gal_01j9m2x9r7",
  "name": "staff-access-lagos",
  "purpose": "verification",
  "retention_days": 365
}
POST/v1/galleries/{gallery_id}/subjectsBearer API KeyIdempotent

Enroll a consented subject into a gallery and store an encrypted embedding template.

ParameterInTypeDescription
gallery_id*pathstringTarget gallery ID.
consent_id*formstringActive consent ID from POST /v1/consents.
images*formfile[]1+ clear facial samples.
Request
curl -X POST https://api.facecore.dev/v1/galleries/gal_01j9m2x9r7/subjects \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F consent_id=cns_01j9m2x9q4 \
  -F images=@enrol_1.jpg
200 OK Response
{
  "request_id": "req_01j9m2x9kd",
  "subject_id": "sub_01j9m2x9s2",
  "gallery_id": "gal_01j9m2x9r7",
  "consent_id": "cns_01j9m2x9q4",
  "template_id": "tpl_01j9m2x9t8",
  "model_id": "arcface-r100-v1",
  "model_version": "1.2.0",
  "quality": 88.4,
  "sample_count": 1
}
POST/v1/galleries/{gallery_id}/identifyBearer API Key

1:N search against a single tenant-isolated gallery with calibrated threshold and margin gap checks.

ParameterInTypeDescription
gallery_id*pathstringGallery ID to search.
image*formfileProbe face image.
profileformstringstrict | standard | relaxed.
Request
curl -X POST https://api.facecore.dev/v1/galleries/gal_01j9m2x9r7/identify \
  -H "Authorization: Bearer $FACECORE_KEY" \
  -F image=@probe.jpg \
  -F profile=standard
200 OK Response
{
  "request_id": "req_01j9m2x9ke",
  "decision_id": "dec_01j9m2x9u1",
  "decision": "MATCH",
  "candidates": [
    { "subject_id": "sub_01j9m2x9s2", "template_id": "tpl_01j9m2x9t8", "score": 0.728 }
  ],
  "threshold": 0.452,
  "margin": 0.312,
  "models": { "embedder": "arcface-r100-v1@1.2.0" },
  "policy_version": "p-2026-01",
  "reasons": []
}
DELETE/v1/subjects/{subject_id}Bearer API Key

Permanently delete a subject's templates from the database and vector index while preserving audit metadata.

ParameterInTypeDescription
subject_id*pathstringSubject ID to erase.
Request
curl -X DELETE https://api.facecore.dev/v1/subjects/sub_01j9m2x9s2 \
  -H "Authorization: Bearer $FACECORE_KEY"
200 OK Response
{
  "request_id": "req_01j9m2x9kf",
  "subject_id": "sub_01j9m2x9s2",
  "deleted": true,
  "index_entries_removed": 1
}