{"openapi":"3.1.0","info":{"title":"InsightFace Server","description":"Simple self-hosted face detection, optional liveness checks, comparison, registration, and search. Image upload endpoints accept JPEG, PNG, WebP, and BMP. Liveness is disabled by default in server.toml, including in legacy configurations that omit inference.addons. Use the Web UI to download and enable liveness for the next startup, or set inference.addons = [\"liveness\"] and install the addon manually. Set inference.addons = [] to disable it. Setting addons.auto_download = [\"liveness\"] includes it when running models install <package>, even when the base package is cached. Mode, threshold, compare scope, and registration policy are server configuration, not request parameters. When evaluated, liveness has status, is_live, and live_score. An input_rejected status means the input could not be evaluated, with both values null and an optional reason containing English retry guidance. Older results may omit reason; successful and fake evaluations have only the three core fields. A missing liveness field means no evaluation was performed. In normal mode, failed or rejected liveness blocks recognition; observe mode continues recognition. Registration skips liveness by default. Install the selected addon before starting the Server; startup does not download models.","version":"0.3.1"},"paths":{"/v1/health":{"get":{"tags":["system"],"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"The process is running but is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/system":{"get":{"tags":["system"],"summary":"System","operationId":"system_v1_system_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/models":{"get":{"tags":["system"],"summary":"Models","operationId":"models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/addons/liveness":{"get":{"tags":["system"],"summary":"Liveness Status","description":"Inspect active liveness, the verified local model, and saved restart settings.\n\nThis is a management endpoint, not a standalone liveness inference API.\nRead-only or single-file config mounts report can_enable=false with an\nactionable unavailable_reason. Checking status never downloads a model.","operationId":"liveness_status_v1_addons_liveness_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivenessManagementResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/addons/liveness/enable":{"post":{"tags":["system"],"summary":"Enable Liveness","description":"Download and verify liveness, then save its next-startup configuration.\n\nSend an empty JSON object. The background job continues after the request\nor browser tab closes; poll GET /v1/addons/liveness for completion. A\nverified cached model is reused. Only after successful verification does\nthe job add liveness to inference.addons and addons.auto_download in the\nconfigured server.toml, preserving other values and comments. Current\ninference does not change: the operator must manually restart Server.\nRepeated requests share the active job. Auth follows other /v1 APIs;\nbrowser requests must originate from this Server or an allowed CORS origin.","operationId":"enable_liveness_v1_addons_liveness_enable_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivenessManagementResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/detect":{"post":{"tags":["faces"],"summary":"Detect","description":"Detect faces without generating recognition embeddings.\n\nWhen the liveness addon is enabled, faces[].liveness contains status,\nis_live, and live_score. HTTP 200 also includes fake faces (status=ok,\nis_live=false) and unsuitable input (status=input_rejected, is_live=null,\nlive_score=null); neither is a detection error. An omitted liveness field\nmeans no evaluation. Rejected input may include liveness.reason with English\nretry guidance; older results may omit it. Successful and fake evaluations\nhave only the three core fields. Model execution failure returns HTTP 503\nliveness_unavailable. There is no separate liveness endpoint.","operationId":"detect_v1_detect_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_detect_v1_detect_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/compare":{"post":{"tags":["faces"],"summary":"Compare","description":"Compare the selected face in each image.\n\nConfigured liveness_compare_scope selects both, source, or target for\nliveness evaluation. In normal mode, a fake or input rejection stops\nrecognition and returns HTTP 422 liveness_fake or liveness_input_rejected;\nerror.details includes liveness and side (source or target). In observe\nmode, comparison continues and each evaluated face includes liveness.\nFor input_rejected, optional liveness.reason provides English retry guidance;\nwhen present, it is also used as error.message.\nUnevaluated sides omit liveness. Runtime faults return HTTP 503\nliveness_unavailable. These policies cannot be overridden per request.","operationId":"compare_v1_compare_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_compare_v1_compare_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/embeddings":{"post":{"tags":["faces"],"summary":"Embeddings","description":"Generate the selected face's recognition embedding.\n\nWith liveness enabled in normal mode, fake faces and unsuitable input\nstop before recognition: HTTP 422 liveness_fake or liveness_input_rejected,\nwith the result in error.details.liveness. For input_rejected, optional\nliveness.reason provides English retry guidance and is used as error.message.\nObserve mode continues recognition and returns faces[].liveness beside the embedding.\nWithout evaluation, liveness is omitted. Runtime faults return HTTP 503\nliveness_unavailable in either mode.","operationId":"embeddings_v1_embeddings_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_embeddings_v1_embeddings_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections":{"post":{"tags":["collections"],"summary":"Create Collection","operationId":"create_collection_v1_collections_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"get":{"tags":["collections"],"summary":"List Collections","operationId":"list_collections_v1_collections_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionPageResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}":{"get":{"tags":["collections"],"summary":"Get Collection","operationId":"get_collection_v1_collections__collection_id__get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"tags":["collections"],"summary":"Patch Collection","operationId":"patch_collection_v1_collections__collection_id__patch","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["collections"],"summary":"Delete Collection","operationId":"delete_collection_v1_collections__collection_id__delete","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/persons":{"post":{"tags":["persons"],"summary":"Create Person","description":"Register a person from one or more images, allowing partial success.\n\nLiveness is skipped by default (liveness_on_registration=false), and new\nsamples omit liveness. When enabled in server.toml, normal mode rejects\nfake or unsuitable images with reason liveness_fake or\nliveness_input_rejected and a separate liveness result in rejected_images.\nRejected input may include liveness.reason with English retry guidance;\nolder results may omit it. This is separate from the rejection category reason.\nObserve mode continues normal registration checks and stores the result\nwith accepted samples. review_mode=off and external_trusted embeddings do\nnot bypass enabled liveness. HTTP 201 may contain accepted faces and\nrejected_images; if all images are rejected, HTTP 422 registration_failed\ncontains error.details.rejected_images. Model faults return HTTP 503\nliveness_unavailable, not a fake verdict.","operationId":"create_person_v1_collections__collection_id__persons_post","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_person_v1_collections__collection_id__persons_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonRegistrationResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"get":{"tags":["persons"],"summary":"List Persons","operationId":"list_persons_v1_collections__collection_id__persons_get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Search"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonPageResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/persons/{person_id}":{"get":{"tags":["persons"],"summary":"Get Person","operationId":"get_person_v1_collections__collection_id__persons__person_id__get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"tags":["persons"],"summary":"Patch Person","operationId":"patch_person_v1_collections__collection_id__persons__person_id__patch","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["persons"],"summary":"Delete Person","operationId":"delete_person_v1_collections__collection_id__persons__person_id__delete","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/persons/{person_id}/faces":{"post":{"tags":["persons"],"summary":"Add Faces","description":"Add images to an existing person, allowing partial success.\n\nLiveness is skipped by default (liveness_on_registration=false). When\nenabled, normal mode rejects fake or unsuitable images with reason\nliveness_fake or liveness_input_rejected and a separate liveness result\nin rejected_images. Observe mode continues other registration checks.\nFor input_rejected, optional liveness.reason contains English retry guidance,\nseparate from the rejection category reason; older results may omit it.\nreview_mode=off and external_trusted embeddings do not bypass enabled\nliveness. HTTP 201 can contain an empty faces list and only rejected_images.\nAccepted samples retain their evaluated liveness result; unevaluated\nsamples omit it. Model faults return HTTP 503 liveness_unavailable.","operationId":"add_faces_v1_collections__collection_id__persons__person_id__faces_post","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_add_faces_v1_collections__collection_id__persons__person_id__faces_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaceRegistrationResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"get":{"tags":["persons"],"summary":"List Faces","operationId":"list_faces_v1_collections__collection_id__persons__person_id__faces_get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacePageResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}/image":{"get":{"tags":["persons"],"summary":"Get Face Image","operationId":"get_face_image_v1_collections__collection_id__persons__person_id__faces__face_id__image_get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}},{"name":"face_id","in":"path","required":true,"schema":{"type":"string","title":"Face Id"}}],"responses":{"200":{"description":"Saved 112 x 112 face crop","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/persons/{person_id}/faces/{face_id}":{"delete":{"tags":["persons"],"summary":"Delete Face","operationId":"delete_face_v1_collections__collection_id__persons__person_id__faces__face_id__delete","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string","title":"Person Id"}},{"name":"face_id","in":"path","required":true,"schema":{"type":"string","title":"Face Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/collections/{collection_id}/search":{"post":{"tags":["search"],"summary":"Search","description":"Search the Collection using the selected face.\n\nWith liveness enabled in normal mode, HTTP 422 liveness_fake or\nliveness_input_rejected stops recognition and index search; the result is\nin error.details.liveness. This is distinct from a valid query with no\nidentity matches. For input_rejected, optional liveness.reason provides\nEnglish retry guidance and is used as error.message. Observe mode continues\nsearch and includes liveness in searched_face. Without evaluation, liveness is omitted. Model faults\nreturn HTTP 503 liveness_unavailable in either mode.","operationId":"search_v1_collections__collection_id__search_post","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_search_v1_collections__collection_id__search_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/monitors":{"post":{"tags":["monitors"],"summary":"Create Monitor","operationId":"create_monitor_v1_monitors_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}}},"429":{"description":"The enabled Monitor capacity is exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"get":{"tags":["monitors"],"summary":"List Monitors","operationId":"list_monitors_v1_monitors_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorPageResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/monitors/{monitor_id}":{"get":{"tags":["monitors"],"summary":"Get Monitor","operationId":"get_monitor_v1_monitors__monitor_id__get","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"patch":{"tags":["monitors"],"summary":"Patch Monitor","operationId":"patch_monitor_v1_monitors__monitor_id__patch","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorResponse"}}}},"429":{"description":"The enabled Monitor capacity is exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["monitors"],"summary":"Delete Monitor","operationId":"delete_monitor_v1_monitors__monitor_id__delete","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/monitors/{monitor_id}/state":{"get":{"tags":["monitors"],"summary":"Monitor State","description":"Read the current RTSP detection and recognition state.\n\nEvaluated faces include the same liveness result as image endpoints:\nstatus, is_live, and live_score, plus optional English reason for input_rejected.\nOlder results may omit reason. In normal mode, blocked faces have status=liveness_blocked and\ncontribute to liveness_blocked_faces, not unknown_faces. They do not run\nidentity search or emit person_enter events. Observe mode continues\nrecognition and identity events. Runtime liveness failures are inference\nerrors and must not be interpreted as fake faces.","operationId":"monitor_state_v1_monitors__monitor_id__state_get","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorStateResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/monitors/{monitor_id}/events":{"get":{"tags":["monitors"],"summary":"Monitor Events","operationId":"monitor_events_v1_monitors__monitor_id__events_get","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorEventPageResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/monitors/{monitor_id}/preview.mjpeg":{"get":{"tags":["monitors"],"summary":"Monitor Preview","operationId":"monitor_preview_v1_monitors__monitor_id__preview_mjpeg_get","parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","title":"Monitor Id"}}],"responses":{"200":{"description":"Live Motion JPEG preview stream.","content":{"multipart/x-mixed-replace":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"AddonPreparationError":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"AddonPreparationError"},"Body_add_faces_v1_collections__collection_id__persons__person_id__faces_post":{"properties":{"images":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Images"},"review_mode":{"type":"string","enum":["off","standard","strict"],"title":"Review Mode","default":"off"},"embedding_mode":{"type":"string","enum":["server","external_trusted"],"title":"Embedding Mode","default":"server"},"external_embeddings":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Embeddings"},"embedding_contract_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Embedding Contract Id"}},"type":"object","required":["images"],"title":"Body_add_faces_v1_collections__collection_id__persons__person_id__faces_post"},"Body_compare_v1_compare_post":{"properties":{"source":{"type":"string","contentMediaType":"application/octet-stream","title":"Source"},"target":{"type":"string","contentMediaType":"application/octet-stream","title":"Target"},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"}},"type":"object","required":["source","target"],"title":"Body_compare_v1_compare_post"},"Body_create_person_v1_collections__collection_id__persons_post":{"properties":{"images":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Images"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"external_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External Id"},"metadata":{"type":"string","title":"Metadata","default":"{}"},"review_mode":{"type":"string","enum":["off","standard","strict"],"title":"Review Mode","default":"off"},"embedding_mode":{"type":"string","enum":["server","external_trusted"],"title":"Embedding Mode","default":"server"},"external_embeddings":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Embeddings"},"embedding_contract_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Embedding Contract Id"}},"type":"object","required":["images"],"title":"Body_create_person_v1_collections__collection_id__persons_post"},"Body_detect_v1_detect_post":{"properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","title":"Image"},"max_faces":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Max Faces"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"min_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Score","deprecated":true}},"type":"object","required":["image"],"title":"Body_detect_v1_detect_post"},"Body_embeddings_v1_embeddings_post":{"properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","title":"Image"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"face_selection":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Face Selection","deprecated":true}},"type":"object","required":["image"],"title":"Body_embeddings_v1_embeddings_post"},"Body_search_v1_collections__collection_id__search_post":{"properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","title":"Image"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":5},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"face_selection":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Face Selection","deprecated":true}},"type":"object","required":["image"],"title":"Body_search_v1_collections__collection_id__search_post"},"BoundingBox":{"properties":{"pixels":{"$ref":"#/components/schemas/PixelBox"},"normalized":{"$ref":"#/components/schemas/NormalizedBox"}},"additionalProperties":true,"type":"object","required":["pixels","normalized"],"title":"BoundingBox"},"Collection":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"default_threshold":{"type":"number","title":"Default Threshold"},"model_id":{"type":"string","title":"Model Id"},"model_digest":{"type":"string","title":"Model Digest"},"embedding_dimension":{"type":"integer","title":"Embedding Dimension"},"preprocessing_version":{"type":"string","title":"Preprocessing Version"},"embedding_contract_id":{"type":"string","title":"Embedding Contract Id"},"search_profile":{"type":"string","title":"Search Profile"},"capacity_rows":{"type":"integer","title":"Capacity Rows"},"max_faces_per_person":{"type":"integer","title":"Max Faces Per Person"},"load_policy":{"type":"string","enum":["eager","lazy"],"title":"Load Policy"},"search_revision":{"type":"integer","title":"Search Revision"},"save_face_crops":{"type":"boolean","title":"Save Face Crops"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"person_count":{"type":"integer","title":"Person Count"},"face_count":{"type":"integer","title":"Face Count"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"detection":{"$ref":"#/components/schemas/DetectionProfile"},"detection_revision":{"type":"integer","title":"Detection Revision"}},"additionalProperties":true,"type":"object","required":["id","name","description","default_threshold","model_id","model_digest","embedding_dimension","preprocessing_version","embedding_contract_id","search_profile","capacity_rows","max_faces_per_person","load_policy","search_revision","save_face_crops","metadata","person_count","face_count","created_at","updated_at","detection","detection_revision"],"title":"Collection"},"CollectionCreate":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"save_face_crops":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Save Face Crops"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"detection":{"$ref":"#/components/schemas/CollectionDetectionCreate"},"search":{"$ref":"#/components/schemas/CollectionSearchCreate"}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"CollectionCreate"},"CollectionDetectionCreate":{"properties":{"input_sizes":{"anyOf":[{"items":{"prefixItems":[{"type":"integer"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"type":"null"}],"title":"Input Sizes"},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"nms_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Nms Threshold"},"single_face_selection":{"anyOf":[{"type":"string","enum":["largest","center_largest"]},{"type":"null"}],"title":"Single Face Selection"}},"additionalProperties":false,"type":"object","title":"CollectionDetectionCreate"},"CollectionDetectionPatch":{"properties":{"input_sizes":{"anyOf":[{"items":{"prefixItems":[{"type":"integer"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"type":"null"}],"title":"Input Sizes"},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"nms_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Nms Threshold"},"single_face_selection":{"anyOf":[{"type":"string","enum":["largest","center_largest"]},{"type":"null"}],"title":"Single Face Selection"}},"additionalProperties":false,"type":"object","title":"CollectionDetectionPatch"},"CollectionPageResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"collections":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array","title":"Collections"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["request_id","collections","next_cursor"],"title":"CollectionPageResponse"},"CollectionPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Threshold"},"save_face_crops":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Save Face Crops"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"detection":{"anyOf":[{"$ref":"#/components/schemas/CollectionDetectionPatch"},{"type":"null"}]},"search":{"anyOf":[{"$ref":"#/components/schemas/CollectionSearchPatch"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"CollectionPatch"},"CollectionResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"collection":{"$ref":"#/components/schemas/Collection"}},"additionalProperties":true,"type":"object","required":["request_id","collection"],"title":"CollectionResponse"},"CollectionSearchCreate":{"properties":{"profile":{"anyOf":[{"type":"string","enum":["fp32_v1","fp16_v1","bf16_v1","int8_x736_v1","int8_x1000_v1"]},{"type":"null"}],"title":"Profile"},"capacity_rows":{"anyOf":[{"type":"integer","maximum":9.223372036854776e+18,"minimum":1.0},{"type":"null"}],"title":"Capacity Rows"},"max_faces_per_person":{"anyOf":[{"type":"integer","maximum":1000000.0,"minimum":1.0},{"type":"null"}],"title":"Max Faces Per Person"},"load_policy":{"anyOf":[{"type":"string","enum":["eager","lazy"]},{"type":"null"}],"title":"Load Policy"}},"additionalProperties":false,"type":"object","title":"CollectionSearchCreate"},"CollectionSearchPatch":{"properties":{"capacity_rows":{"anyOf":[{"type":"integer","maximum":9.223372036854776e+18,"minimum":1.0},{"type":"null"}],"title":"Capacity Rows"},"max_faces_per_person":{"anyOf":[{"type":"integer","maximum":1000000.0,"minimum":1.0},{"type":"null"}],"title":"Max Faces Per Person"},"load_policy":{"anyOf":[{"type":"string","enum":["eager","lazy"]},{"type":"null"}],"title":"Load Policy"}},"additionalProperties":false,"type":"object","title":"CollectionSearchPatch"},"CompareResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"matched":{"type":"boolean","title":"Matched"},"similarity":{"type":"number","title":"Similarity"},"threshold":{"type":"number","title":"Threshold"},"source_face":{"$ref":"#/components/schemas/FaceObservation"},"target_face":{"$ref":"#/components/schemas/FaceObservation"},"processing_ms":{"type":"number","title":"Processing Ms"}},"additionalProperties":true,"type":"object","required":["request_id","matched","similarity","threshold","source_face","target_face","processing_ms"],"title":"CompareResponse"},"DetectResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"faces":{"items":{"$ref":"#/components/schemas/FaceObservation"},"type":"array","title":"Faces"},"processing_ms":{"type":"number","title":"Processing Ms"}},"additionalProperties":true,"type":"object","required":["request_id","faces","processing_ms"],"title":"DetectResponse"},"DetectionProfile":{"properties":{"input_sizes":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Input Sizes"},"threshold":{"type":"number","title":"Threshold"},"nms_threshold":{"type":"number","title":"Nms Threshold"},"single_face_selection":{"type":"string","enum":["largest","center_largest"],"title":"Single Face Selection"}},"additionalProperties":true,"type":"object","required":["input_sizes","threshold","nms_threshold","single_face_selection"],"title":"DetectionProfile"},"EmbeddingsResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"faces":{"items":{"$ref":"#/components/schemas/FaceObservation"},"type":"array","title":"Faces"},"model":{"$ref":"#/components/schemas/ModelSummary"},"processing_ms":{"type":"number","title":"Processing Ms"}},"additionalProperties":true,"type":"object","required":["request_id","faces","model","processing_ms"],"title":"EmbeddingsResponse"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"additionalProperties":true,"type":"object","title":"Details"}},"additionalProperties":true,"type":"object","required":["code","message","details"],"title":"ErrorBody"},"ErrorEnvelope":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}},"request_id":{"type":"string","format":"uuid"}}},"FaceObservation":{"properties":{"bbox":{"$ref":"#/components/schemas/BoundingBox"},"landmarks":{"items":{"items":{"type":"number"},"type":"array"},"type":"array","title":"Landmarks"},"detection_score":{"type":"number","title":"Detection Score"},"quality":{"$ref":"#/components/schemas/FaceQuality"},"embedding":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Embedding"},"liveness":{"anyOf":[{"$ref":"#/components/schemas/LivenessResult"},{"type":"null"}],"description":"Omitted when liveness was not evaluated for this face."}},"additionalProperties":true,"type":"object","required":["bbox","landmarks","detection_score","quality"],"title":"FaceObservation"},"FacePageResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"faces":{"items":{"$ref":"#/components/schemas/FaceSample"},"type":"array","title":"Faces"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["request_id","faces","next_cursor"],"title":"FacePageResponse"},"FaceQuality":{"properties":{"score":{"type":"number","title":"Score"},"sharpness":{"type":"number","title":"Sharpness"},"brightness":{"type":"number","title":"Brightness"},"pose":{"type":"number","title":"Pose"}},"additionalProperties":true,"type":"object","required":["score","sharpness","brightness","pose"],"title":"FaceQuality"},"FaceRegistrationResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"faces":{"items":{"$ref":"#/components/schemas/FaceSample"},"type":"array","title":"Faces"},"rejected_images":{"items":{"$ref":"#/components/schemas/RejectedImage"},"type":"array","title":"Rejected Images"}},"additionalProperties":true,"type":"object","required":["request_id","faces","rejected_images"],"title":"FaceRegistrationResponse"},"FaceSample":{"properties":{"id":{"type":"string","title":"Id"},"person_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Person Id"},"bounding_box":{"$ref":"#/components/schemas/BoundingBox"},"landmarks":{"anyOf":[{"items":{"items":{"type":"number"},"type":"array"},"type":"array"},{"type":"null"}],"title":"Landmarks"},"detection_score":{"type":"number","title":"Detection Score"},"quality":{"$ref":"#/components/schemas/FaceQuality"},"model_id":{"type":"string","title":"Model Id"},"model_digest":{"type":"string","title":"Model Digest"},"preprocessing_version":{"type":"string","title":"Preprocessing Version"},"embedding_source":{"type":"string","enum":["server","external_trusted"],"title":"Embedding Source"},"embedding_contract_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Embedding Contract Id"},"has_crop":{"type":"boolean","title":"Has Crop"},"created_at":{"type":"string","title":"Created At"},"liveness":{"anyOf":[{"$ref":"#/components/schemas/LivenessResult"},{"type":"null"}],"description":"Saved evaluation from registration, omitted when no evaluation occurred. Historical results remain available even if liveness is now disabled."}},"additionalProperties":true,"type":"object","required":["id","bounding_box","landmarks","detection_score","quality","model_id","model_digest","preprocessing_version","embedding_source","embedding_contract_id","has_crop","created_at"],"title":"FaceSample"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"status":{"type":"string","enum":["ready","not_ready"],"title":"Status"},"version":{"type":"string","title":"Version"},"auth_enabled":{"type":"boolean","title":"Auth Enabled"}},"additionalProperties":true,"type":"object","required":["request_id","status","version","auth_enabled"],"title":"HealthResponse"},"LivenessManagementResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether liveness is active in the running Server."},"installed":{"type":"boolean","title":"Installed","description":"Whether the local addon passes the official SHA256 check."},"configured_enabled":{"type":"boolean","title":"Configured Enabled","description":"Whether the current on-disk config enables liveness for the next startup."},"restart_required":{"type":"boolean","title":"Restart Required","description":"The saved liveness selection differs from the running Server."},"can_enable":{"type":"boolean","title":"Can Enable"},"unavailable_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unavailable Code","description":"Stable reason code for clients to localize unavailable_reason; null when preparation is available."},"unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unavailable Reason"},"state":{"type":"string","enum":["idle","downloading","ready","error"],"title":"State"},"error":{"anyOf":[{"$ref":"#/components/schemas/AddonPreparationError"},{"type":"null"}]},"model_path":{"type":"string","title":"Model Path"},"config_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Config File"}},"additionalProperties":true,"type":"object","required":["request_id","enabled","installed","configured_enabled","restart_required","can_enable","unavailable_code","unavailable_reason","state","error","model_path","config_file"],"title":"LivenessManagementResponse"},"LivenessResult":{"properties":{"status":{"type":"string","enum":["ok","input_rejected"],"title":"Status","description":"ok means the model evaluated the face, including fake verdicts. input_rejected means the input does not meet liveness requirements (for example, insufficient image coverage near an edge)."},"is_live":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Live","description":"For status=ok, true or false according to the configured liveness_threshold. Null only for input_rejected; it does not mean the addon is disabled."},"live_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Live Score","description":"Live probability from 0 to 1 for status=ok; null for input_rejected."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Optional English explanation and retry guidance, present only for input_rejected. Older results may omit it. Omitted for status=ok."}},"additionalProperties":false,"type":"object","required":["status","is_live","live_score"],"title":"LivenessResult","description":"Three core fields describe the evaluation; rejected input may also include reason.\n\nLive: {\"status\":\"ok\",\"is_live\":true,\"live_score\":0.98}.\nFake: {\"status\":\"ok\",\"is_live\":false,\"live_score\":0.12}.\nUnsuitable input: {\"status\":\"input_rejected\",\"is_live\":null,\"live_score\":null}.\nFor input_rejected, optional reason is an English explanation with guidance for retrying.\nOlder results may omit reason. Successful and fake evaluations have only the three core fields."},"Match":{"properties":{"person":{"$ref":"#/components/schemas/Person"},"similarity":{"type":"number","title":"Similarity"},"matched_face_id":{"type":"string","title":"Matched Face Id"}},"additionalProperties":true,"type":"object","required":["person","similarity","matched_face_id"],"title":"Match"},"ModelComponent":{"properties":{"model_id":{"type":"string","title":"Model Id"},"task":{"type":"string","title":"Task"},"sha256":{"type":"string","title":"Sha256"},"file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File"},"input_size":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Input Size"},"embedding_dimension":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Embedding Dimension"},"preprocessing_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preprocessing Version"}},"additionalProperties":true,"type":"object","required":["model_id","task","sha256"],"title":"ModelComponent"},"ModelSummary":{"properties":{"model_id":{"type":"string","title":"Model Id"},"model_digest":{"type":"string","title":"Model Digest"},"embedding_dimension":{"type":"integer","title":"Embedding Dimension"},"preprocessing_version":{"type":"string","title":"Preprocessing Version"},"provider":{"type":"string","title":"Provider"},"models":{"items":{"$ref":"#/components/schemas/ModelComponent"},"type":"array","title":"Models"},"license":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"License"},"addons":{"anyOf":[{"items":{"$ref":"#/components/schemas/ModelComponent"},"type":"array"},{"type":"null"}],"title":"Addons"}},"additionalProperties":true,"type":"object","required":["model_id","model_digest","embedding_dimension","preprocessing_version","provider","models","license"],"title":"ModelSummary"},"ModelsResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"models":{"items":{"$ref":"#/components/schemas/ModelComponent"},"type":"array","title":"Models"},"execution_provider":{"type":"string","title":"Execution Provider"},"license":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"License"},"addons":{"anyOf":[{"items":{"$ref":"#/components/schemas/ModelComponent"},"type":"array"},{"type":"null"}],"title":"Addons"}},"additionalProperties":true,"type":"object","required":["request_id","models","execution_provider","license"],"title":"ModelsResponse"},"Monitor":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"enabled":{"type":"boolean","title":"Enabled"},"source":{"$ref":"#/components/schemas/MonitorSource-Output"},"collection_id":{"type":"string","title":"Collection Id"},"inference_fps":{"type":"number","title":"Inference Fps"},"match_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Match Threshold"},"event_buffer_size":{"type":"integer","title":"Event Buffer Size"},"event_policy":{"$ref":"#/components/schemas/MonitorEventPolicy-Output"},"preview_enabled":{"type":"boolean","title":"Preview Enabled"},"runtime":{"$ref":"#/components/schemas/MonitorRuntime"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"additionalProperties":true,"type":"object","required":["id","name","description","enabled","source","collection_id","inference_fps","match_threshold","event_buffer_size","event_policy","preview_enabled","runtime","created_at","updated_at"],"title":"Monitor"},"MonitorCreate":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"enabled":{"type":"boolean","title":"Enabled","default":true},"source":{"$ref":"#/components/schemas/MonitorSource-Input"},"collection_id":{"type":"string","title":"Collection Id"},"inference_fps":{"type":"number","maximum":30.0,"minimum":0.1,"title":"Inference Fps","default":2.0},"match_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Match Threshold"},"event_buffer_size":{"type":"integer","maximum":10000.0,"minimum":10.0,"title":"Event Buffer Size","default":1000},"event_policy":{"$ref":"#/components/schemas/MonitorEventPolicy-Input"},"preview_enabled":{"type":"boolean","title":"Preview Enabled","default":false}},"additionalProperties":false,"type":"object","required":["id","name","source","collection_id"],"title":"MonitorCreate"},"MonitorEvent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"sequence":{"type":"integer","title":"Sequence"},"type":{"type":"string","title":"Type"},"monitor_id":{"type":"string","title":"Monitor Id"},"stream_epoch":{"type":"string","title":"Stream Epoch"},"occurred_at":{"type":"string","title":"Occurred At"},"track_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Id"},"person":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Person"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Threshold"},"matched_face_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Face Id"},"face":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Face"},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error"}},"additionalProperties":true,"type":"object","required":["id","sequence","type","monitor_id","stream_epoch","occurred_at"],"title":"MonitorEvent"},"MonitorEventPageResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"monitor_id":{"type":"string","title":"Monitor Id"},"stream_epoch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stream Epoch"},"events":{"items":{"$ref":"#/components/schemas/MonitorEvent"},"type":"array","title":"Events"},"oldest_sequence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Oldest Sequence"},"latest_sequence":{"type":"integer","title":"Latest Sequence"},"has_more":{"type":"boolean","title":"Has More"},"truncated":{"type":"boolean","title":"Truncated"},"stream_reset":{"type":"boolean","title":"Stream Reset"},"next_cursor":{"type":"string","title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["request_id","monitor_id","stream_epoch","events","oldest_sequence","latest_sequence","has_more","truncated","stream_reset","next_cursor"],"title":"MonitorEventPageResponse"},"MonitorEventPolicy-Input":{"properties":{"confirm_frames":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Confirm Frames","default":3},"absence_timeout_seconds":{"type":"number","maximum":300.0,"minimum":0.1,"title":"Absence Timeout Seconds","default":3.0},"cooldown_seconds":{"type":"number","maximum":3600.0,"minimum":0.0,"title":"Cooldown Seconds","default":10.0},"emit_unknown":{"type":"boolean","title":"Emit Unknown","default":true}},"additionalProperties":false,"type":"object","title":"MonitorEventPolicy"},"MonitorEventPolicy-Output":{"properties":{"confirm_frames":{"type":"integer","title":"Confirm Frames"},"absence_timeout_seconds":{"type":"number","title":"Absence Timeout Seconds"},"cooldown_seconds":{"type":"number","title":"Cooldown Seconds"},"emit_unknown":{"type":"boolean","title":"Emit Unknown"}},"additionalProperties":true,"type":"object","required":["confirm_frames","absence_timeout_seconds","cooldown_seconds","emit_unknown"],"title":"MonitorEventPolicy"},"MonitorEventPolicyPatch":{"properties":{"confirm_frames":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Confirm Frames"},"absence_timeout_seconds":{"anyOf":[{"type":"number","maximum":300.0,"minimum":0.1},{"type":"null"}],"title":"Absence Timeout Seconds"},"cooldown_seconds":{"anyOf":[{"type":"number","maximum":3600.0,"minimum":0.0},{"type":"null"}],"title":"Cooldown Seconds"},"emit_unknown":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Emit Unknown"}},"additionalProperties":false,"type":"object","title":"MonitorEventPolicyPatch"},"MonitorInferenceState":{"properties":{"configured_fps":{"type":"number","title":"Configured Fps"},"actual_fps":{"type":"number","title":"Actual Fps"},"processing_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Processing Ms"},"last_frame_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Frame At"},"last_inference_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Inference At"},"frame_sequence":{"type":"integer","title":"Frame Sequence"},"decoded_frames":{"type":"integer","title":"Decoded Frames"},"processed_frames":{"type":"integer","title":"Processed Frames"},"dropped_frames":{"type":"integer","title":"Dropped Frames"},"capacity_limited":{"type":"boolean","title":"Capacity Limited"}},"additionalProperties":true,"type":"object","required":["configured_fps","actual_fps","processing_ms","last_frame_at","last_inference_at","frame_sequence","decoded_frames","processed_frames","dropped_frames","capacity_limited"],"title":"MonitorInferenceState"},"MonitorPageResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"monitors":{"items":{"$ref":"#/components/schemas/Monitor"},"type":"array","title":"Monitors"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["request_id","monitors","next_cursor"],"title":"MonitorPageResponse"},"MonitorPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"source":{"anyOf":[{"$ref":"#/components/schemas/MonitorSource-Input"},{"type":"null"}]},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"inference_fps":{"anyOf":[{"type":"number","maximum":30.0,"minimum":0.1},{"type":"null"}],"title":"Inference Fps"},"match_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Match Threshold"},"event_buffer_size":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":10.0},{"type":"null"}],"title":"Event Buffer Size"},"event_policy":{"anyOf":[{"$ref":"#/components/schemas/MonitorEventPolicyPatch"},{"type":"null"}]},"preview_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Preview Enabled"}},"additionalProperties":false,"type":"object","title":"MonitorPatch"},"MonitorPreviewState":{"properties":{"enabled":{"type":"boolean","title":"Enabled"},"active":{"type":"boolean","title":"Active"},"viewers":{"type":"integer","title":"Viewers"},"frames":{"type":"integer","title":"Frames"}},"additionalProperties":true,"type":"object","required":["enabled","active","viewers","frames"],"title":"MonitorPreviewState"},"MonitorResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"monitor":{"$ref":"#/components/schemas/Monitor"}},"additionalProperties":true,"type":"object","required":["request_id","monitor"],"title":"MonitorResponse"},"MonitorRuntime":{"properties":{"status":{"type":"string","title":"Status"},"connected":{"type":"boolean","title":"Connected"},"stream_epoch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stream Epoch"},"last_frame_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Frame At"},"last_error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"title":"Last Error"},"preview_active":{"type":"boolean","title":"Preview Active"},"preview_viewers":{"type":"integer","title":"Preview Viewers"}},"additionalProperties":true,"type":"object","required":["status","connected","stream_epoch","last_frame_at","last_error","preview_active","preview_viewers"],"title":"MonitorRuntime"},"MonitorSource-Input":{"properties":{"type":{"type":"string","const":"rtsp","title":"Type","default":"rtsp"},"url":{"type":"string","maxLength":2048,"minLength":8,"title":"Url"}},"additionalProperties":false,"type":"object","required":["url"],"title":"MonitorSource"},"MonitorSource-Output":{"properties":{"type":{"type":"string","const":"rtsp","title":"Type"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["type","url"],"title":"MonitorSource"},"MonitorState":{"properties":{"monitor_id":{"type":"string","title":"Monitor Id"},"stream_epoch":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stream Epoch"},"status":{"type":"string","title":"Status"},"connected":{"type":"boolean","title":"Connected"},"source":{"$ref":"#/components/schemas/MonitorStateSource"},"inference":{"$ref":"#/components/schemas/MonitorInferenceState"},"threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Threshold"},"faces":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Faces"},"matched_faces":{"type":"integer","title":"Matched Faces"},"unknown_faces":{"type":"integer","title":"Unknown Faces"},"liveness_blocked_faces":{"type":"integer","title":"Liveness Blocked Faces","description":"Faces blocked by normal-mode liveness; counted separately from unknown_faces and excluded from identity search and person_enter events.","default":0},"preview":{"$ref":"#/components/schemas/MonitorPreviewState"},"reconnects":{"type":"integer","title":"Reconnects"},"inference_errors":{"type":"integer","title":"Inference Errors"},"last_error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"title":"Last Error"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"}},"additionalProperties":true,"type":"object","required":["monitor_id","stream_epoch","status","connected","source","inference","threshold","faces","matched_faces","unknown_faces","preview","reconnects","inference_errors","last_error","started_at"],"title":"MonitorState"},"MonitorStateResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"state":{"$ref":"#/components/schemas/MonitorState"}},"additionalProperties":true,"type":"object","required":["request_id","state"],"title":"MonitorStateResponse"},"MonitorStateSource":{"properties":{"width":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Width"},"height":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Height"},"source_fps":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Source Fps"}},"additionalProperties":true,"type":"object","required":["width","height","source_fps"],"title":"MonitorStateSource"},"NormalizedBox":{"properties":{"left":{"type":"number","title":"Left"},"top":{"type":"number","title":"Top"},"width":{"type":"number","title":"Width"},"height":{"type":"number","title":"Height"}},"additionalProperties":true,"type":"object","required":["left","top","width","height"],"title":"NormalizedBox"},"Person":{"properties":{"id":{"type":"string","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"face_count":{"type":"integer","title":"Face Count"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"additionalProperties":true,"type":"object","required":["id","name","external_id","metadata","face_count","created_at","updated_at"],"title":"Person"},"PersonPageResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"persons":{"items":{"$ref":"#/components/schemas/Person"},"type":"array","title":"Persons"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"additionalProperties":true,"type":"object","required":["request_id","persons","next_cursor"],"title":"PersonPageResponse"},"PersonPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"external_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"additionalProperties":false,"type":"object","title":"PersonPatch"},"PersonRegistrationResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"person":{"$ref":"#/components/schemas/Person"},"faces":{"items":{"$ref":"#/components/schemas/FaceSample"},"type":"array","title":"Faces"},"rejected_images":{"items":{"$ref":"#/components/schemas/RejectedImage"},"type":"array","title":"Rejected Images"}},"additionalProperties":true,"type":"object","required":["request_id","person","faces","rejected_images"],"title":"PersonRegistrationResponse"},"PersonResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"person":{"$ref":"#/components/schemas/Person"}},"additionalProperties":true,"type":"object","required":["request_id","person"],"title":"PersonResponse"},"PixelBox":{"properties":{"x":{"type":"integer","title":"X"},"y":{"type":"integer","title":"Y"},"width":{"type":"integer","title":"Width"},"height":{"type":"integer","title":"Height"}},"additionalProperties":true,"type":"object","required":["x","y","width","height"],"title":"PixelBox"},"RejectedImage":{"properties":{"index":{"type":"integer","title":"Index"},"filename":{"type":"string","title":"Filename"},"reason":{"type":"string","title":"Reason","description":"Actual rejection reason, such as low_quality, liveness_fake, or liveness_input_rejected. A separate liveness result does not replace this reason."},"liveness":{"anyOf":[{"$ref":"#/components/schemas/LivenessResult"},{"type":"null"}],"description":"Supplemental evaluation when available, including rejection for other reasons. Omitted when liveness was not evaluated."}},"additionalProperties":true,"type":"object","required":["index","filename","reason"],"title":"RejectedImage"},"SearchResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"searched_face":{"$ref":"#/components/schemas/FaceObservation"},"matches":{"items":{"$ref":"#/components/schemas/Match"},"type":"array","title":"Matches"},"threshold":{"type":"number","title":"Threshold"},"processing_ms":{"type":"number","title":"Processing Ms"}},"additionalProperties":true,"type":"object","required":["request_id","searched_face","matches","threshold","processing_ms"],"title":"SearchResponse"},"SystemResponse":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"server_version":{"type":"string","title":"Server Version"},"os":{"type":"string","title":"Os"},"architecture":{"type":"string","title":"Architecture"},"cpu":{"additionalProperties":true,"type":"object","title":"Cpu"},"runtime":{"additionalProperties":true,"type":"object","title":"Runtime"},"execution_provider":{"type":"string","title":"Execution Provider"},"model":{"$ref":"#/components/schemas/ModelSummary"},"database":{"additionalProperties":true,"type":"object","title":"Database"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"models":{"additionalProperties":true,"type":"object","title":"Models"},"stats":{"additionalProperties":{"type":"integer"},"type":"object","title":"Stats"},"search":{"additionalProperties":true,"type":"object","title":"Search"},"api_key":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Api Key"},"safe_config":{"additionalProperties":true,"type":"object","title":"Safe Config"},"recent_errors":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Recent Errors"}},"additionalProperties":true,"type":"object","required":["request_id","server_version","os","architecture","cpu","runtime","execution_provider","model","database","data","models","stats","search","api_key","safe_config","recent_errors"],"title":"SystemResponse"},"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"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}