{"openapi":"3.1.0","info":{"title":"FaceMatch Pro Sample","version":"0.1.0"},"paths":{"/api/register":{"post":{"summary":"Register","description":"얼굴등록 (멀티임베딩 + PII-free 파트너 키).\n이미지 1~N장을 받아 각 프레임의 임베딩을 뽑고 품질게이트를 통과한 것만 저장.\n식별키 = unique_key (없으면 mobile 로 폴백=데모/구버전 호환). group_key 로 학원 스코프.\nname·mobile·extra(JSON) 등 부가정보는 AES 로 암호화(extra_enc)해 저장하고 매칭 시 그대로 반환.\n대표(frontal 또는 첫 장)는 faces.embedding, 전체는 face_embeddings 에 포즈별 저장.","operationId":"register_api_register_post","parameters":[{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_register_api_register_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/detect":{"post":{"summary":"Detect","operationId":"detect_api_detect_post","parameters":[{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_detect_api_detect_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/multi-detect":{"post":{"summary":"Multi Detect","operationId":"multi_detect_api_multi_detect_post","parameters":[{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_multi_detect_api_multi_detect_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/faces":{"get":{"summary":"Api List Faces","description":"앱: 자기 회사의 등록 얼굴 목록.\n부가정보(extra)는 복호화해 내려주고, name/mobile 은 extra(우선) 또는\n구버전 평문 컬럼에서 병합(_person_payload 와 동일 규칙). extra_enc 원문은 미노출.","operationId":"api_list_faces_api_faces_get","parameters":[{"name":"license_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"License Key"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/faces/{fid}/poses":{"get":{"summary":"Api Face Poses","description":"앱: 등록 얼굴 상세 — 포즈별 등록 이미지 + 식별키 + 복호화된 부가정보.\n(관리자 /admin/faces/{id}/poses 와 동일 정보를 회사코드 인증으로 제공)","operationId":"api_face_poses_api_faces__fid__poses_get","parameters":[{"name":"fid","in":"path","required":true,"schema":{"type":"integer","title":"Fid"}},{"name":"license_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"License Key"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/logs":{"get":{"summary":"Api Logs","description":"앱: 자기 회사의 최근 매칭 로그. 대상 이름은 로그 평문 → 부가정보 → 등록 평문\n순으로 병합하고 암호문(extra_enc)은 노출하지 않는다.","operationId":"api_logs_api_logs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"license_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"License Key"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/faces/{fid}":{"post":{"summary":"Api Update Face","description":"앱: 등록 얼굴 이름·연락처 수정 (임베딩/사진 유지).\n신규 구조에선 name/mobile 이 부가정보(extra, 암호화)라 extra 에 병합 저장하고,\n구버전 화면(관리자 목록 등)이 읽는 평문 컬럼도 함께 갱신해 표시를 일치시킨다.","operationId":"api_update_face_api_faces__fid__post","parameters":[{"name":"fid","in":"path","required":true,"schema":{"type":"integer","title":"Fid"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_api_update_face_api_faces__fid__post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Api Delete Face","description":"앱: 등록 얼굴 삭제.","operationId":"api_delete_face_api_faces__fid__delete","parameters":[{"name":"fid","in":"path","required":true,"schema":{"type":"integer","title":"Fid"}},{"name":"license_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"License Key"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/faces/by-key/{unique_key}":{"delete":{"summary":"Api Delete Face By Key","description":"앱/외부연동: 등록 시 사용한 파트너 식별키(unique_key)로 얼굴 삭제.\nface_id 를 몰라도 삭제할 수 있다. group_key 는 옵션 —\n전달하면 해당 스코프만, 생략하면 회사 내 해당 식별키 전체를 삭제한다.","operationId":"api_delete_face_by_key_api_faces_by_key__unique_key__delete","parameters":[{"name":"unique_key","in":"path","required":true,"schema":{"type":"string","title":"Unique Key"}},{"name":"group_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"Group Key"}},{"name":"license_key","in":"query","required":false,"schema":{"type":"string","default":"","title":"License Key"}},{"name":"x-license-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-License-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_api_update_face_api_faces__fid__post":{"properties":{"name":{"type":"string","title":"Name","default":""},"mobile":{"type":"string","title":"Mobile","default":""},"license_key":{"type":"string","title":"License Key","default":""}},"type":"object","title":"Body_api_update_face_api_faces__fid__post"},"Body_detect_api_detect_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"threshold":{"type":"number","title":"Threshold","default":-1.0},"min_face_ratio":{"type":"number","title":"Min Face Ratio","default":-1.0},"margin":{"type":"number","title":"Margin","default":-1.0},"group_key":{"type":"string","title":"Group Key","default":""},"license_key":{"type":"string","title":"License Key","default":""}},"type":"object","required":["file"],"title":"Body_detect_api_detect_post"},"Body_multi_detect_api_multi_detect_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"threshold":{"type":"number","title":"Threshold","default":-1.0},"margin":{"type":"number","title":"Margin","default":-1.0},"group_key":{"type":"string","title":"Group Key","default":""},"license_key":{"type":"string","title":"License Key","default":""}},"type":"object","required":["file"],"title":"Body_multi_detect_api_multi_detect_post"},"Body_register_api_register_post":{"properties":{"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files","default":[]},"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File"},"poses":{"type":"string","title":"Poses","default":""},"unique_key":{"type":"string","title":"Unique Key","default":""},"group_key":{"type":"string","title":"Group Key","default":""},"extra":{"type":"string","title":"Extra","default":""},"name":{"type":"string","title":"Name","default":""},"mobile":{"type":"string","title":"Mobile","default":""},"license_key":{"type":"string","title":"License Key","default":""}},"type":"object","title":"Body_register_api_register_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}