# Face Registry API

Base URL: https://face-ai.luuanh.online

- Human docs: https://face-ai.luuanh.online/docs
- OpenAPI 3.1 (all operations, parameters, bodies, responses and schemas): https://face-ai.luuanh.online/openapi.json
- Complete contract as text: https://face-ai.luuanh.online/llms-full.txt

Data APIs require Authorization: Bearer YOUR_API_TOKEN. Never put tokens in URLs.
GET /api/faces writes count_found; retries increment again. It chooses up to 5 random rows from the first 10 matching IDs ascending, does not mark used, and always returns next_cursor=null. Use used_status=false for unused rows. Calls can return the same rows again.
GET /api/faces/manage and /api/faces/exists are read-only. The management list accepts filename as a partial filename filter. PATCH /api/faces/:id with JSON {"used":true} marks that exact record used; retries are idempotent and count_found is unchanged. PATCH /api/faces/toggle-used marks only the newest exact provider/username/sha256_background match used=true; retries keep the same row used. DELETE /api/faces requires both username and provider query parameters and deletes every exact matching face row, including used rows and duplicates; returns data.deleted_count (0 on retry). No request body or additional filters. Remote download files remain untouched. There is no reservation API. See the contract for supported operations; do not infer missing operations.