Face-scan API — documentation

Basics

Ye API rate API se bilkul alag hai — apna namespace (/api/face-scan/*), apni table (face_scan_keystores) aur apna code folder (src/face-scan/). Rates / passkeys / sections se iska koi lena-dena nahi.

Base URL http://localhost:3000. Sab kuch JSON hai, response ka shape fix hai:

{ "ok": true,  "data": … }        // success
{ "ok": false, "error": "…" }     // failure

Kaise kaam karta hai

1. Pehle ek keystore_id aur uska url store karo (keys page /face-scan/admin se ya API se).
2. Koi bhi client us keystore_id se lookup call karta hai.
3. Response me wahi url milta hai.

POST /api/face-scan/keystores   { "keystore_id": "ks_1001", "url": "https://scan.example.com/s/ks_1001" }
                                   (koi passkey / secret nahi)

GET  /api/face-scan/url/ks_1001
  -> { "ok": true, "data": { "keystore_id": "ks_1001", "url": "https://scan.example.com/s/ks_1001" } }

Ek keystore_id = ek url. Url badalna ho to PATCH karo — client ko wahi id se naya url milne lagega.

Authentication

Koi authentication nahi hai. Face-scan ki kisi bhi call me passkey, secret ya key nahi lagti — na url lene me, na store / edit / delete me. Rate API ki passkeys se iska koi lena-dena nahi.

URL lookup

Teeno tarike ek hi kaam karte hain — jo suit kare:

copy# 1. path me
curl http://localhost:3000/api/face-scan/url/ks_1001

# 2. query me
curl "http://localhost:3000/api/face-scan/url?keystore_id=ks_1001"

# 3. body me
curl -X POST http://localhost:3000/api/face-scan/url \
     -H 'content-type: application/json' \
     -d '{"keystore_id":"ks_1001"}'

Response:

{
  "ok": true,
  "data": {
    "keystore_id": "ks_1001",
    "url": "https://scan.example.com/s/ks_1001"
  }
}

Har successful lookup par us keystore ka hits +1 aur last_used_at update hota hai (GET /api/face-scan/keystores/:keystore_id me dikhta hai).

Keystores — store / edit / delete

copy# store
curl -X POST http://localhost:3000/api/face-scan/keystores \
     -H 'content-type: application/json' -H "x-passkey: $ADMIN" \
     -d '{"keystore_id":"ks_1001","url":"https://scan.example.com/s/ks_1001","label":"Gate 1"}'

# url badlo
curl -X PATCH http://localhost:3000/api/face-scan/keystores/ks_1001 \
     -H 'content-type: application/json' -H "x-passkey: $ADMIN" \
     -d '{"url":"https://scan.example.com/s/ks_1001_v2"}'

# band karo (delete kiye bina) -- lookup 403 dega
curl -X PATCH http://localhost:3000/api/face-scan/keystores/ks_1001 \
     -H 'content-type: application/json' -H "x-passkey: $ADMIN" \
     -d '{"active":false}'

# sab dekho / hatao
curl http://localhost:3000/api/face-scan/keystorescurl -X DELETE http://localhost:3000/api/face-scan/keystores/ks_1001 -H "x-passkey: $ADMIN"

Create ka response:

{
  "ok": true,
  "data": {
    "keystore_id": "ks_1001",
    "url": "https://scan.example.com/s/ks_1001",
    "label": "Gate 1",
    "active": true,
    "hits": 0,
    "last_used_at": null,
    "created_by": null,
    "created_at": "2026-09-11 10:00:00",
    "updated_at": "2026-09-11 10:00:00"
  }
}

Validation

• keystore_id — caller deta hai (auto nahi banta), max 200 chars, space / / / control character nahi (path me bhi jaata hai).
• url — poora http:// ya https:// url, max 2048 chars. javascript:, ftp:, relative path — sab 400.
• label — optional, max 120 chars.
• Wahi keystore_id dobara POST kiya — 409, badalna ho to PATCH.

Errors

Analytics actions

Face-scan ki har call bhi wahi analytics table me log hoti hai (dashboard ke Request log me dikhti hai), target_id me keystore_id.

• face_scan.lookup — url lookup
• face_scan.list, face_scan.get, face_scan.create, face_scan.update, face_scan.delete — store / edit / delete
• face_scan.disabled — band keystore ka lookup

Table

Core wali SQLite file (DB_PATH) me hi, pehli start par apne aap banti hai.

face_scan_keystores
  keystore_id   TEXT PRIMARY KEY   -- caller deta hai
  url           TEXT NOT NULL      -- lookup par yahi milta hai
  label         TEXT
  active        INTEGER            -- 0 = lookup 403
  hits          INTEGER            -- successful lookups
  last_used_at  TEXT
  created_by    TEXT               -- passkey ke saath banaya ho to uski id, warna null
  created_at    TEXT
  updated_at    TEXT

Code: src/face-scan/store.js (table + validation), src/face-scan/routes.js (saare routes), src/face-scan/docs.html (ye page), src/face-scan/test.js (npm run test:face-scan).