{ "openapi": "3.0.4", "info": { "title": "VerifEye - Verify API", "version": "v1" }, "servers": [ { "url": "/" } ], "paths": { "/v1/collection/get": { "get": { "tags": [ "Collection" ], "summary": "Retrieves a single collection by its identifier.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The collection identifier.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } } ], "responses": { "200": { "description": "Collection found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetCollectionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetCollectionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetCollectionResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/collection/get-all": { "get": { "tags": [ "Collection" ], "summary": "Lists all collections belonging to the authenticated account.", "responses": { "200": { "description": "Collections returned.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetAllCollectionsResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetAllCollectionsResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetAllCollectionsResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/collection/create": { "post": { "tags": [ "Collection" ], "summary": "Creates a new collection.", "requestBody": { "description": "Payload containing collection id and optional description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateCollectionRequest" } } } }, "responses": { "200": { "description": "Collection created successfully.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateCollectionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Collection already exists.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/collection/update": { "put": { "tags": [ "Collection" ], "summary": "Updates an existing collection (only description is mutable).", "requestBody": { "description": "Payload containing collection id and new description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionRequest" } } } }, "responses": { "200": { "description": "Collection updated.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UpdateCollectionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/collection/reset": { "delete": { "tags": [ "Collection" ], "summary": "Removes all indexed faces from a collection without deleting the collection itself.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The collection identifier.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } } ], "responses": { "200": { "description": "Collection reset (all faces removed).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ResetCollectionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ResetCollectionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ResetCollectionResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/collection/delete": { "delete": { "tags": [ "Collection" ], "summary": "Deletes a collection by its identifier.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The collection identifier.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } } ], "responses": { "200": { "description": "Collection deleted.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteCollectionResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCollectionResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteCollectionResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/external-key/get-face-ids": { "get": { "tags": [ "ExternalKey" ], "summary": "Returns all face ids associated with the specified external key in a collection.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The collection identifier.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } }, { "name": "externalKey", "in": "query", "description": "The external key to look up.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[\\x21-\\x7E]{1,512}$", "type": "string" } } ], "responses": { "200": { "description": "Lookup succeeded.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GetExternalKeyResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GetExternalKeyResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GetExternalKeyResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/external-key/set": { "put": { "tags": [ "ExternalKey" ], "summary": "Associates an external key with a face. Creates a new association or updates the existing one.", "requestBody": { "description": "The collection, face, external key and duplicate policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetExternalKeyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SetExternalKeyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SetExternalKeyRequest" } } } }, "responses": { "200": { "description": "Association created or updated.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/SetExternalKeyResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SetExternalKeyResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SetExternalKeyResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure, or the external key is a duplicate and duplicates are not allowed.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/external-key/delete": { "delete": { "tags": [ "ExternalKey" ], "summary": "Removes external key associations. When the face id is omitted, every face associated with\nthe external key is unlinked; otherwise only the single pair is removed.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The collection identifier.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } }, { "name": "externalKey", "in": "query", "description": "The external key whose associations are removed.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[\\x21-\\x7E]{1,512}$", "type": "string" } }, { "name": "faceId", "in": "query", "description": "Optional. When omitted, all pairs for the external key are removed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Associations removed (idempotent).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteExternalKeyResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteExternalKeyResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteExternalKeyResponse" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/face/onboard": { "post": { "tags": [ "Face" ], "summary": "Onboards the faces on the image into the collection: every face is looked up and, when it is not\nalready there, added.", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OnboardRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OnboardRequestModel" } } } }, "responses": { "200": { "description": "The faces were onboarded.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/OnboardResultModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/OnboardResultModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OnboardResultModel" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "The request did not complete within the time budget." } } } }, "/v1/face/identify": { "post": { "tags": [ "Face" ], "summary": "Identifies the faces on the image against the collection: every face is looked up and never added.", "requestBody": { "description": "Request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/IdentifyRequestModel" } } } }, "responses": { "200": { "description": "The faces were searched for; each one either matched or did not.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/IdentifyResultModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyResultModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/IdentifyResultModel" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "The request did not complete within the time budget." } } } }, "/v1/face/compare-embeddings": { "post": { "tags": [ "Face" ], "summary": "Compares two face embeddings and returns how similar they are. The embeddings are the ones onboard and\nidentify return for a face. No collection is involved and nothing is stored.", "requestBody": { "description": "The two embeddings to compare.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsRequestModel" } } } }, "responses": { "200": { "description": "The embeddings were compared.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsResultModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsResultModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CompareEmbeddingsResultModel" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/face/delete": { "delete": { "tags": [ "Face" ], "summary": "Deletes a single face from the collection.", "parameters": [ { "name": "collectionId", "in": "query", "description": "The id of the collection the face belongs to.", "required": true, "schema": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string" } }, { "name": "faceId", "in": "query", "description": "The id of the face to be deleted.", "required": true, "schema": { "maxLength": 64, "minLength": 0, "type": "string" } } ], "responses": { "200": { "description": "The face was deleted (idempotent).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteFaceResultModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFaceResultModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteFaceResultModel" } } } }, "401": { "description": "Authentication failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Validation failure.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Collection not found.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/healthz": { "get": { "tags": [ "Health" ], "summary": "Returns the server UTC time.", "responses": { "200": { "description": "Returns the server UTC time.", "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "text/json": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "AgeEstimationModel": { "type": "object", "properties": { "prediction": { "type": "number", "description": "Estimated age", "format": "float", "nullable": true }, "uncertainty": { "type": "number", "description": "Uncertainty score of the estimation with value range [0.0, infinity], we recommend rejecting everything higher than 1.0. Values higher than this can be indicative of a problem with the image quality.", "format": "float", "nullable": true } }, "additionalProperties": false, "description": "Estimated age of a face. Returned only when requested via Verify.Api.Services.Recognition.Models.FaceAttributeOptions.Age." }, "AttentionModel": { "type": "object", "properties": { "presence": { "type": "boolean", "description": "Describes whether a person is present in the image. (Null means, that it could not be determined reliably)", "nullable": true }, "eyesOnScreen": { "type": "boolean", "description": "Describes whether the person's eyes are on the screen. (Null means, that it could not be determined reliably)", "nullable": true }, "attention": { "type": "boolean", "description": "Describes whether the person is attentive. (Null means, that it could not be determined reliably)", "nullable": true } }, "additionalProperties": false, "description": "Detected attention metrics of a face. Returned only when requested via\nVerify.Api.Services.Recognition.Models.FaceAttributeOptions.Attention. A null property means the corresponding state could not be\ndetermined reliably from the image." }, "BoundingBoxModel": { "type": "object", "properties": { "x": { "type": "integer", "description": "Horizontal position of the detected face bounding box", "format": "int32" }, "y": { "type": "integer", "description": "Vertical position of the detected face bounding box", "format": "int32" }, "width": { "type": "integer", "description": "Width of the detected face bounding box", "format": "int32" }, "height": { "type": "integer", "description": "Height of the detected face bounding box", "format": "int32" } }, "additionalProperties": false, "description": "Model for the bounding box of a detected face" }, "CollectionModel": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Identifier of the collection.", "nullable": true }, "description": { "type": "string", "description": "Optional textual description.", "nullable": true }, "createdAt": { "type": "string", "description": "UTC timestamp when the collection was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "UTC timestamp when the collection was last updated.", "format": "date-time" } }, "additionalProperties": false, "description": "Detailed collection model." }, "CollectionOverviewModel": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Identifier of the collection.", "nullable": true }, "description": { "type": "string", "description": "Optional textual description.", "nullable": true }, "createdAt": { "type": "string", "description": "UTC timestamp when the collection was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "UTC timestamp when the collection was last updated.", "format": "date-time" } }, "additionalProperties": false, "description": "Lightweight overview of a collection." }, "CompareEmbeddingsRequestModel": { "required": [ "embedding1", "embedding2" ], "type": "object", "properties": { "embedding1": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "The embedding to compare." }, "embedding2": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "The embedding to compare it with." } }, "additionalProperties": false, "description": "Request model for comparing two face embeddings. Both must be embeddings returned by onboard or identify\nvia Verify.Api.Services.Recognition.Models.FaceAttributeOptions.Embedding." }, "CompareEmbeddingsResultModel": { "type": "object", "properties": { "similarity": { "type": "integer", "description": "Similarity of the two embeddings with value range [1, 100] (higher is better).\nReject any matches where similarity is less than 70; 80 is the recommended operating point.\n95 corresponds to FPR 1e-06 / 90 corresponds to FPR 1e-05 / 80 corresponds to FPR 1e-4 / 70 corresponds to FPR 1e-3\nAll thresholds were computed using our extensive in-the-wild datasets", "format": "int32" } }, "additionalProperties": false, "description": "Model for the result of comparing two face embeddings." }, "CreateCollectionRequest": { "required": [ "collectionId" ], "type": "object", "properties": { "collectionId": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string", "description": "Unique identifier for the collection (max length 512).", "example": "MyCollectionId" }, "description": { "maxLength": 1024, "type": "string", "description": "Optional description (max length 1024).", "nullable": true } }, "additionalProperties": false, "description": "Request payload for creating a new collection." }, "CreateCollectionResponse": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Identifier of the created collection.", "nullable": true } }, "additionalProperties": false, "description": "Response after creating a new collection." }, "DeleteCollectionResponse": { "type": "object", "additionalProperties": false, "description": "Response for a successful collection deletion." }, "DeleteExternalKeyResponse": { "type": "object", "additionalProperties": false, "description": "Result marker for deleting external key associations." }, "DeleteFaceResultModel": { "type": "object", "additionalProperties": false, "description": "Model for the result of deleting a face from a collection." }, "EmotionsModel": { "type": "object", "properties": { "confusion": { "type": "boolean", "description": "Describes whether the person shows confusion. (Null means, that it could not be determined reliably)", "nullable": true }, "contempt": { "type": "boolean", "description": "Describes whether the person shows contempt. (Null means, that it could not be determined reliably)", "nullable": true }, "disgust": { "type": "boolean", "description": "Describes whether the person shows disgust. (Null means, that it could not be determined reliably)", "nullable": true }, "happy": { "type": "boolean", "description": "Describes whether the person shows happiness. (Null means, that it could not be determined reliably)", "nullable": true }, "empathy": { "type": "boolean", "description": "Describes whether the person shows empathy. (Null means, that it could not be determined reliably)", "nullable": true }, "surprise": { "type": "boolean", "description": "Describes whether the person shows surprise. (Null means, that it could not be determined reliably)", "nullable": true } }, "additionalProperties": false, "description": "Detected emotions of a face. Returned only when requested via Verify.Api.Services.Recognition.Models.FaceAttributeOptions.Emotions.\nA null property means the corresponding state could not be determined reliably from the image." }, "ExternalKeySetResultType": { "enum": [ "Created", "Updated" ], "type": "string", "description": "Indicates whether a set operation created a new association or updated an existing one." }, "FaceAttributeOptions": { "type": "object", "properties": { "embedding": { "type": "boolean", "description": "When true, the face verification embedding of the face is returned." }, "age": { "type": "boolean", "description": "When true, the estimated age of the face is returned." }, "gender": { "type": "boolean", "description": "When true, the detected gender of the face is returned." }, "emotions": { "type": "boolean", "description": "When true, the detected emotions of the face are returned." }, "attention": { "type": "boolean", "description": "When true, the detected facial presence and attention of the face are returned." } }, "additionalProperties": false, "description": "Selects which optional attributes are returned for each face in addition to its face id. Every option\ndefaults to false; enable only the ones you need to keep responses small." }, "FaceDetectionModel": { "type": "object", "properties": { "confidence": { "type": "number", "description": "Face detection score with value range [0.0, 1.0] (higher is better)", "format": "float" }, "boundingBox": { "$ref": "#/components/schemas/BoundingBoxModel" } }, "additionalProperties": false, "description": "Model for face detection" }, "FaceResultModel": { "type": "object", "properties": { "face": { "$ref": "#/components/schemas/FaceDetectionModel" }, "faceId": { "type": "string", "description": "The id of the face", "nullable": true }, "externalKey": { "type": "string", "description": "The external key associated with the face, when one has been set via the external key API. Null otherwise.", "nullable": true }, "embedding": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "Face verification embedding of this face. Populated only when requested via Verify.Api.Services.Recognition.Models.FaceAttributeOptions.Embedding.", "nullable": true }, "age": { "$ref": "#/components/schemas/AgeEstimationModel" }, "gender": { "$ref": "#/components/schemas/Gender" }, "emotions": { "$ref": "#/components/schemas/EmotionsModel" }, "attention": { "$ref": "#/components/schemas/AttentionModel" }, "faceStatus": { "$ref": "#/components/schemas/FaceStatus" } }, "additionalProperties": false, "description": "Result for a single face detected on the image." }, "FaceStatus": { "enum": [ "NotExisting", "New", "Existing" ], "type": "string", "description": "Whether a face was matched to an identity in the collection, added to it, or returned without one." }, "Gender": { "enum": [ "Male", "Female" ], "type": "string", "description": "Detected gender" }, "GetAllCollectionsResponse": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionOverviewModel" }, "description": "Collections returned for the account (may be empty).", "nullable": true } }, "additionalProperties": false, "description": "Response containing the list of collections for an account." }, "GetCollectionResponse": { "type": "object", "properties": { "collection": { "$ref": "#/components/schemas/CollectionModel" } }, "additionalProperties": false, "description": "Response containing a single collection's details." }, "GetExternalKeyResponse": { "type": "object", "properties": { "faceIds": { "type": "array", "items": { "type": "string" }, "description": "The ids of the faces associated with the external key. Empty when none are associated.", "nullable": true } }, "additionalProperties": false, "description": "Result of looking up the faces associated with an external key." }, "IdentifyRequestModel": { "required": [ "collectionId" ], "type": "object", "properties": { "image": { "$ref": "#/components/schemas/ImageModel" }, "collectionId": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string", "description": "The id of the collection to operate against" }, "faceMatchThreshold": { "maximum": 100, "minimum": 0, "type": "integer", "description": "(Optional) Specifies the minimum confidence in the face match to return. For example, don't return any matches where confidence in matches is less than 70. The default value is 80.\n95 corresponds to FPR 1e-06 / 90 corresponds to FPR 1e-05 / 80 corresponds to FPR 1e-4 / 70 corresponds to FPR 1e-3\nAll thresholds were computed using our extensive in-the-wild datasets\nValid Range: Minimum value of 0. Maximum value of 100.", "format": "int32", "default": 80 }, "include": { "$ref": "#/components/schemas/FaceAttributeOptions" }, "maxFaces": { "maximum": 4, "minimum": 1, "type": "integer", "description": "(Optional) The maximum number of faces to return. If more than this number of faces are detected, only the dominant faces will be used and the rest will be ignored. The default value is 1.\nValid Range: Minimum value of 1. Maximum value of 4.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request model for identifying faces against a collection. Every face on the image is looked up in the\ncollection; nothing is ever added to it." }, "IdentifyResultModel": { "type": "object", "properties": { "faces": { "type": "array", "items": { "$ref": "#/components/schemas/FaceResultModel" }, "description": "The faces that were identified, one entry per face.", "nullable": true }, "unprocessedFaceCount": { "type": "integer", "description": "Number of faces that were detected on the image but not returned, because\nVerify.Api.Services.Recognition.Models.FaceOperationRequestModel.MaxFaces limited how many are processed.", "format": "int32" } }, "additionalProperties": false, "description": "Result of an identify operation." }, "ImageModel": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of a jpeg or png image", "nullable": true }, "bytes": { "type": "string", "description": "Base 64 string encoded binary jpeg or png image", "nullable": true } }, "additionalProperties": false, "description": "Represents an image using either a URL or a Base64 string encoded string." }, "OnboardRequestModel": { "required": [ "collectionId" ], "type": "object", "properties": { "image": { "$ref": "#/components/schemas/ImageModel" }, "collectionId": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string", "description": "The id of the collection to operate against" }, "faceMatchThreshold": { "maximum": 100, "minimum": 0, "type": "integer", "description": "(Optional) Specifies the minimum confidence in the face match to return. For example, don't return any matches where confidence in matches is less than 70. The default value is 80.\n95 corresponds to FPR 1e-06 / 90 corresponds to FPR 1e-05 / 80 corresponds to FPR 1e-4 / 70 corresponds to FPR 1e-3\nAll thresholds were computed using our extensive in-the-wild datasets\nValid Range: Minimum value of 0. Maximum value of 100.", "format": "int32", "default": 80 }, "include": { "$ref": "#/components/schemas/FaceAttributeOptions" }, "maxFaces": { "maximum": 4, "minimum": 1, "type": "integer", "description": "(Optional) The maximum number of faces to return. If more than this number of faces are detected, only the dominant faces will be used and the rest will be ignored. The default value is 1.\nValid Range: Minimum value of 1. Maximum value of 4.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Request model for onboarding faces into a collection. Every face on the image is looked up in the\ncollection and added to it when it is not already there." }, "OnboardResultModel": { "type": "object", "properties": { "faces": { "type": "array", "items": { "$ref": "#/components/schemas/FaceResultModel" }, "description": "The faces that were onboarded, one entry per face.", "nullable": true }, "unprocessedFaceCount": { "type": "integer", "description": "Number of faces that were detected on the image but not returned, because\nVerify.Api.Services.Recognition.Models.FaceOperationRequestModel.MaxFaces limited how many are processed.", "format": "int32" } }, "additionalProperties": false, "description": "Result of an onboard operation." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } }, "ResetCollectionResponse": { "type": "object", "properties": { "collectionId": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Response for a successful collection reset (all faces removed, collection preserved)." }, "SetExternalKeyRequest": { "required": [ "collectionId", "externalKey", "faceId" ], "type": "object", "properties": { "collectionId": { "maxLength": 512, "minLength": 0, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string", "description": "The id of the collection the face belongs to." }, "faceId": { "maxLength": 64, "minLength": 0, "type": "string", "description": "The id of the face to associate the external key with." }, "externalKey": { "maxLength": 512, "minLength": 0, "pattern": "^[\\x21-\\x7E]{1,512}$", "type": "string", "description": "The external key to associate with the face. Maximum 512 printable ASCII characters." }, "allowDuplicates": { "type": "boolean", "description": "When false (default), the request is rejected with 400 if the external key is already\nassociated with a different face. When true, the external key may map to multiple faces." } }, "additionalProperties": false, "description": "Request model for associating an external key with a face." }, "SetExternalKeyResponse": { "type": "object", "properties": { "faceId": { "type": "string", "description": "The id of the face the external key was associated with.", "nullable": true }, "externalKey": { "type": "string", "description": "The external key that was associated.", "nullable": true }, "result": { "$ref": "#/components/schemas/ExternalKeySetResultType" } }, "additionalProperties": false, "description": "Result of associating an external key with a face." }, "UpdateCollectionRequest": { "required": [ "collectionId" ], "type": "object", "properties": { "collectionId": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "type": "string", "description": "Identifier of the collection to update." }, "description": { "maxLength": 1024, "type": "string", "description": "New description (max length 1024).", "nullable": true } }, "additionalProperties": false, "description": "Request payload for updating an existing collection.\nOnly description is editable." }, "UpdateCollectionResponse": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Identifier of the updated collection.", "nullable": true } }, "additionalProperties": false, "description": "Response after updating a collection." } }, "securitySchemes": { "Bearer": { "type": "http", "description": "JWT Authorization header using the Bearer scheme. \r\n\r\n Enter your token in the text input below.\r\n\r\nExample: \"1safsfsdfd...\"", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKey": { "type": "apiKey", "description": "API key Authorization header using the ApiKey scheme. \r\n\r\n Enter 'ApiKey' [space] and then your APIKey in the text input below.\r\n\r\nExample: \"ApiKey 5j3245lj...\"", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [ ], "ApiKey": [ ] } ], "tags": [ { "name": "Collection" }, { "name": "ExternalKey" }, { "name": "Face" }, { "name": "Health" } ] }