> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/backend1n/technical_documentation/api_reference/models.md).

# Models

## The ImageBuffer object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ImageBuffer":{"type":"string","description":"Image buffer in JPEG, PNG or BMP format, encoded in RFC4648 base64."}}}}
```

## The FacialTemplate object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FacialTemplate":{"type":"string","description":"Facial biometric template, encoded in RFC4648 base64. It is a timestamped token: extracting the same image twice produces different values (it changes every second), so it must not be compared or used as a key. It is not the input of any endpoint.\n"}}}}
```

## The FacialTemplateRaw object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"}}}}
```

## The UpdatedTemplateRaw object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"UpdatedTemplateRaw":{"type":"boolean","default":false,"description":"If true, the returned templateRaw is new (it was generated or updated in this operation) and it should be stored in place of the previous one. When extracting from an image it is true; when extracting from a valid templateRaw (`/extract/template`) it is false.\n"}}}}
```

## The BinaryImage object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"BinaryImage":{"type":"string","format":"binary","description":"Binary image data in JPEG, PNG or BMP format, sent or received as is (not encoded in base64 or in any other text format)."}}}}
```

## The FaceId object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."}}}}
```

## The CollectionId object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"}}}}
```

## The MediaId object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"}}}}
```

## The MimeType object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MimeType":{"type":"string","description":"Identifier of the file format (`image/jpeg`, `image/png` or `image/bmp`). If not included, it defaults to 'image/jpeg'. It is the value that will be returned as `Content-Type` when the image is downloaded.\n"}}}}
```

## The TemplateRawExraction object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"TemplateRawExraction":{"type":"boolean","default":false,"description":"If true, the templateRaw will be computed and returned. If false or omitted, the response does not include `facialTemplateRaw`.\n"}}}}
```

## The MaxCandidates object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MaxCandidates":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of candidates wanted in the response. Unsigned integer greater than or equal to 1 (a negative, decimal or textual value, or one greater than the range of a 64-bit unsigned integer, is rejected with 400).\n"}}}}
```

## The MinSimilarity object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MinSimilarity":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"The minimum similarity required for a candidate to be included in the response. Number between 0 and 1 (inclusive); any other value is rejected with 400. With the default value (0), candidates of any similarity are returned up to `maxCandidates`: the search does **not** apply the SDK authentication threshold (`FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD`, 65); to keep only positive matches, sending `minSimilarity: 0.65` is recommended.\n"}}}}
```

## The Similarity object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"Similarity":{"type":"number","default":0,"description":"A value between 0 and 1 that indicates the similarity between two biometric templates."}}}}
```

## The GalleryIndex object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"GalleryIndex":{"type":"integer","minimum":0,"description":"The position (0-based, unique within the response) that an item occupies in the collection gallery."}}}}
```

## The ExtractOptions object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ExtractOptions":{"type":"object","description":"Options when extracting biometric templates.","properties":{"templateRawExtraction":{"$ref":"#/components/schemas/TemplateRawExraction"}}},"TemplateRawExraction":{"type":"boolean","default":false,"description":"If true, the templateRaw will be computed and returned. If false or omitted, the response does not include `facialTemplateRaw`.\n"}}}}
```

## The SearchOptions object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"SearchOptions":{"type":"object","description":"Options when searching for biometric templates.","properties":{"maxCandidates":{"$ref":"#/components/schemas/MaxCandidates"},"minSimilarity":{"$ref":"#/components/schemas/MinSimilarity"}}},"MaxCandidates":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of candidates wanted in the response. Unsigned integer greater than or equal to 1 (a negative, decimal or textual value, or one greater than the range of a 64-bit unsigned integer, is rejected with 400).\n"},"MinSimilarity":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"The minimum similarity required for a candidate to be included in the response. Number between 0 and 1 (inclusive); any other value is rejected with 400. With the default value (0), candidates of any similarity are returned up to `maxCandidates`: the search does **not** apply the SDK authentication threshold (`FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD`, 65); to keep only positive matches, sending `minSimilarity: 0.65` is recommended.\n"}}}}
```

## The FaceDescription object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."}}}}
```

## The CreateAt object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"CreateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was created."}}}}
```

## The UpdateAt object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"UpdateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was updated."}}}}
```

## The TimeStamp object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The ExtractBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ExtractBody":{"type":"object","description":"Body for the extract request","properties":{"image":{"$ref":"#/components/schemas/ImageBuffer"},"options":{"$ref":"#/components/schemas/ExtractOptions"}},"required":["image"]},"ImageBuffer":{"type":"string","description":"Image buffer in JPEG, PNG or BMP format, encoded in RFC4648 base64."},"ExtractOptions":{"type":"object","description":"Options when extracting biometric templates.","properties":{"templateRawExtraction":{"$ref":"#/components/schemas/TemplateRawExraction"}}},"TemplateRawExraction":{"type":"boolean","default":false,"description":"If true, the templateRaw will be computed and returned. If false or omitted, the response does not include `facialTemplateRaw`.\n"}}}}
```

## The ExtractTemplateBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ExtractTemplateBody":{"type":"object","description":"Body for the extraction request from a template","properties":{"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"options":{"$ref":"#/components/schemas/ExtractOptions"}},"required":["facialTemplateRaw"]},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"ExtractOptions":{"type":"object","description":"Options when extracting biometric templates.","properties":{"templateRawExtraction":{"$ref":"#/components/schemas/TemplateRawExraction"}}},"TemplateRawExraction":{"type":"boolean","default":false,"description":"If true, the templateRaw will be computed and returned. If false or omitted, the response does not include `facialTemplateRaw`.\n"}}}}
```

## The AssetUploadBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"AssetUploadBody":{"type":"object","description":"Body for the asset upload request in `multipart/form-data`","properties":{"file":{"$ref":"#/components/schemas/BinaryImage"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"mimeType":{"$ref":"#/components/schemas/MimeType"}},"required":["file","collectionId"]},"BinaryImage":{"type":"string","format":"binary","description":"Binary image data in JPEG, PNG or BMP format, sent or received as is (not encoded in base64 or in any other text format)."},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"MimeType":{"type":"string","description":"Identifier of the file format (`image/jpeg`, `image/png` or `image/bmp`). If not included, it defaults to 'image/jpeg'. It is the value that will be returned as `Content-Type` when the image is downloaded.\n"}}}}
```

## The CollectionCreateBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"CollectionCreateBody":{"type":"object","description":"Body for the POST request to create a collection","properties":{"collectionId":{"$ref":"#/components/schemas/CollectionId"}},"required":["collectionId"]},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"}}}}
```

## The FaceBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FaceBody":{"type":"object","description":"Body for the POST face request","properties":{"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"description":{"$ref":"#/components/schemas/FaceDescription"}},"required":["mediaId","collectionId","description"]},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."}}}}
```

## The FaceUpdateBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FaceUpdateBody":{"type":"object","description":"Body for the PUT face request. All fields are optional, but `mediaId` and `collectionId` must appear together in the same request or neither of them must appear - changing the collection without also specifying the target mediaId is not allowed.","properties":{"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"description":{"$ref":"#/components/schemas/FaceDescription"}}},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."}}}}
```

## The SearchImageBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"SearchImageBody":{"type":"object","description":"Body for the POST request to search by image","properties":{"image":{"$ref":"#/components/schemas/ImageBuffer"},"options":{"$ref":"#/components/schemas/SearchOptions"}},"required":["image"]},"ImageBuffer":{"type":"string","description":"Image buffer in JPEG, PNG or BMP format, encoded in RFC4648 base64."},"SearchOptions":{"type":"object","description":"Options when searching for biometric templates.","properties":{"maxCandidates":{"$ref":"#/components/schemas/MaxCandidates"},"minSimilarity":{"$ref":"#/components/schemas/MinSimilarity"}}},"MaxCandidates":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of candidates wanted in the response. Unsigned integer greater than or equal to 1 (a negative, decimal or textual value, or one greater than the range of a 64-bit unsigned integer, is rejected with 400).\n"},"MinSimilarity":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"The minimum similarity required for a candidate to be included in the response. Number between 0 and 1 (inclusive); any other value is rejected with 400. With the default value (0), candidates of any similarity are returned up to `maxCandidates`: the search does **not** apply the SDK authentication threshold (`FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD`, 65); to keep only positive matches, sending `minSimilarity: 0.65` is recommended.\n"}}}}
```

## The SearchTemplateBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"SearchTemplateBody":{"type":"object","description":"Body for the POST request to search by template","properties":{"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"options":{"$ref":"#/components/schemas/SearchOptions"}},"required":["facialTemplateRaw"]},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"SearchOptions":{"type":"object","description":"Options when searching for biometric templates.","properties":{"maxCandidates":{"$ref":"#/components/schemas/MaxCandidates"},"minSimilarity":{"$ref":"#/components/schemas/MinSimilarity"}}},"MaxCandidates":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of candidates wanted in the response. Unsigned integer greater than or equal to 1 (a negative, decimal or textual value, or one greater than the range of a 64-bit unsigned integer, is rejected with 400).\n"},"MinSimilarity":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"The minimum similarity required for a candidate to be included in the response. Number between 0 and 1 (inclusive); any other value is rejected with 400. With the default value (0), candidates of any similarity are returned up to `maxCandidates`: the search does **not** apply the SDK authentication threshold (`FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD`, 65); to keep only positive matches, sending `minSimilarity: 0.65` is recommended.\n"}}}}
```

## The ConfigBody object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ConfigBody":{"type":"object","description":"Body for the config request. This endpoint does not accept JWT authentication parameters or network or logger parameters: a request that includes them, or whose `config_json_string` is not a valid JSON object, must be rejected with 400.\n","properties":{"config_json_string":{"type":"string","description":"String that contains a JSON object with the service configuration parameters."}},"required":["config_json_string"]}}}}
```

## The ExtractResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ExtractResponse":{"type":"object","description":"Biometric extraction response. `facialTemplateRaw` is only present if the request asked for `templateRawExtraction: true`.\n","properties":{"facialTemplate":{"$ref":"#/components/schemas/FacialTemplate"},"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"updatedTemplateRaw":{"$ref":"#/components/schemas/UpdatedTemplateRaw"}}},"FacialTemplate":{"type":"string","description":"Facial biometric template, encoded in RFC4648 base64. It is a timestamped token: extracting the same image twice produces different values (it changes every second), so it must not be compared or used as a key. It is not the input of any endpoint.\n"},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"UpdatedTemplateRaw":{"type":"boolean","default":false,"description":"If true, the returned templateRaw is new (it was generated or updated in this operation) and it should be stored in place of the previous one. When extracting from an image it is true; when extracting from a valid templateRaw (`/extract/template`) it is false.\n"}}}}
```

## The UploadMediaResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"UploadMediaResponse":{"type":"object","description":"Media upload response. The identifier is returned in `id` (elsewhere in the API this same value is called `mediaId`).","properties":{"id":{"$ref":"#/components/schemas/MediaId"}}},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"}}}}
```

## The CollectionResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"CollectionResponse":{"type":"object","description":"Data of the created collection","properties":{"collectionId":{"$ref":"#/components/schemas/CollectionId"}}},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"}}}}
```

## The CollectionsListResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"CollectionsListResponse":{"type":"array","description":"A list of collectionIds existing in the database. If none matches the given prefix, an empty list is returned (it is not an error).","items":{"$ref":"#/components/schemas/CollectionId"}},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"}}}}
```

## The FaceResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FaceResponse":{"type":"object","description":"Data fields of the specimen in the database","properties":{"createAt":{"$ref":"#/components/schemas/CreateAt"},"description":{"$ref":"#/components/schemas/FaceDescription"},"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"id":{"$ref":"#/components/schemas/FaceId"},"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"updateAt":{"$ref":"#/components/schemas/UpdateAt"}}},"CreateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was created."},"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"UpdateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was updated."}}}}
```

## The FacesResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"FacesResponse":{"type":"array","description":"Data fields of several specimens in the database","items":{"$ref":"#/components/schemas/FaceResponse"}},"FaceResponse":{"type":"object","description":"Data fields of the specimen in the database","properties":{"createAt":{"$ref":"#/components/schemas/CreateAt"},"description":{"$ref":"#/components/schemas/FaceDescription"},"facialTemplateRaw":{"$ref":"#/components/schemas/FacialTemplateRaw"},"id":{"$ref":"#/components/schemas/FaceId"},"mediaId":{"$ref":"#/components/schemas/MediaId"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"updateAt":{"$ref":"#/components/schemas/UpdateAt"}}},"CreateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was created."},"FaceDescription":{"type":"string","minLength":1,"description":"Description of the specimen (face) stored in the database."},"FacialTemplateRaw":{"type":"string","description":"An extended token that contains biometric templates and metadata. Storing it in databases is recommended because it remains valid across engine versions (it can be updated automatically if the extraction technology changes; see `updatedTemplateRaw`). Like the rest of the tokens, its value changes on every extraction (it carries a timestamp): two extractions of the same image do not give the same text, but they identify the same person. It is encoded in RFC4648 base64.\n"},"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"UpdateAt":{"type":"string","description":"Date/time value (UTC, 1-second resolution) in \"%Y-%m-%dT%H:%M:%SZ\" format at which a specimen (face) was updated."}}}}
```

## The SearchItem object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"SearchItem":{"type":"object","description":"Specimen found in the database. `templateId` is the `id` of the specimen (face) found.","properties":{"galleryIndex":{"$ref":"#/components/schemas/GalleryIndex"},"similarity":{"$ref":"#/components/schemas/Similarity"},"templateId":{"$ref":"#/components/schemas/FaceId"}}},"GalleryIndex":{"type":"integer","minimum":0,"description":"The position (0-based, unique within the response) that an item occupies in the collection gallery."},"Similarity":{"type":"number","default":0,"description":"A value between 0 and 1 that indicates the similarity between two biometric templates."},"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."}}}}
```

## The SearchResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"SearchResponse":{"type":"array","description":"A list of specimens (faces) found in the database, sorted by descending similarity and with at most `maxCandidates` items.\n","items":{"$ref":"#/components/schemas/SearchItem"}},"SearchItem":{"type":"object","description":"Specimen found in the database. `templateId` is the `id` of the specimen (face) found.","properties":{"galleryIndex":{"$ref":"#/components/schemas/GalleryIndex"},"similarity":{"$ref":"#/components/schemas/Similarity"},"templateId":{"$ref":"#/components/schemas/FaceId"}}},"GalleryIndex":{"type":"integer","minimum":0,"description":"The position (0-based, unique within the response) that an item occupies in the collection gallery."},"Similarity":{"type":"number","default":0,"description":"A value between 0 and 1 that indicates the similarity between two biometric templates."},"FaceId":{"type":"string","description":"An identifier of a specimen (face) in the database."}}}}
```

## The ConfigResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ConfigResult":{"type":"object","description":"JSON object with the service configuration parameters exposed by the management endpoint. The JWT authentication parameters, `logger_file_prefix` and the `metrics_*` parameters are not included.\n","properties":{"port":{"type":"integer"},"number_of_threads":{"type":"integer","description":"I/O threads. 0 = number of CPU cores. Without `config.json` the default value is 1."},"connection_timeout":{"type":"integer","description":"Seconds a connection stays alive without reads or writes (0 = no limit)."},"keep_alive_request_number":{"type":"integer","description":"Maximum requests per keep-alive connection (0 = no limit)."},"client_max_body_size":{"type":"integer","description":"Maximum body size in MB."},"logger_path":{"type":"string","description":"Base path of the logs. Without `config.json` the default value is `/service/config`."},"logger_level":{"type":"string","enum":["trace","debug","info","warning","error","critical","off"]},"logger_rotation":{"type":"string","enum":["hourly","daily"]},"logger_max_files":{"type":"integer"}}}}}}
```

## The BadRequestResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"BadRequestResult":{"type":"object","description":"Result when incorrect parameters arrive in the request.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Specific description of the reason for the error. It is the only field that indicates the real cause."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The ExceptionResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"ExceptionResult":{"type":"object","description":"An error occurred while calling the backend services.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Specific description of the reason for the exception (internal service text; it is not part of the contract)."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The UnauthorizedResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"UnauthorizedResult":{"type":"object","description":"JWT authentication is enabled and the request does not pass it. It is accompanied by the header `WWW-Authenticate: Bearer`. Values of `message`: `Missing authentication token` (no token or unsupported scheme), `JWT token validation failed` (invalid signature, algorithm or format), `JWT token is expired`, `JWT token does not include exp claim` and `JWT token is not yet valid` (future `nbf`).\n","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The HealthSdkState object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"HealthSdkState":{"type":"object","description":"State of the biometric SDK.","properties":{"healthy":{"type":"boolean"},"initialized":{"type":"boolean"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string if there is none."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastHealthKnown":{"type":"boolean"},"lastInitStatus":{"type":"string"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The HealthStatus object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"HealthStatus":{"type":"string","description":"Result of the health service (indicates whether the SDK is active or not).","enum":["Healthy","Unhealthy"]}}}}
```

## The HealthResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"HealthResult":{"type":"object","description":"The result of a health check.","properties":{"message":{"$ref":"#/components/schemas/HealthStatus"},"initialized":{"type":"boolean","description":"Whether the SDK started correctly when the service started."},"sdk":{"$ref":"#/components/schemas/HealthSdkState"}}},"HealthStatus":{"type":"string","description":"Result of the health service (indicates whether the SDK is active or not).","enum":["Healthy","Unhealthy"]},"HealthSdkState":{"type":"object","description":"State of the biometric SDK.","properties":{"healthy":{"type":"boolean"},"initialized":{"type":"boolean"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string if there is none."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastHealthKnown":{"type":"boolean"},"lastInitStatus":{"type":"string"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The VersionResult object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"VersionResult":{"type":"object","description":"The result of a version check.","properties":{"version":{"type":"string","description":"Service version number followed by the copyright notice, in a single text. It must not be parsed looking only for the version number without taking the rest of the string into account."}}}}}}
```

## The MetricsClassification object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MetricsClassification":{"type":"string","description":"Summary of the operational state of the service, derived solely from the published snapshot. The rules are evaluated in this order and the first one that is met wins: `unhealthy` (the SDK did not start or the last known health check is negative), `saturated`, `degraded`, `unknown` (no request has been served yet and health has not been checked), `idle` and `ok`. The numeric thresholds are the `metrics_*` parameters described in the installation manual.\n","enum":["ok","degraded","saturated","idle","unhealthy","unknown"]}}}}
```

## The MetricsAlert object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MetricsAlert":{"type":"object","description":"Actionable alert derived from the snapshot.","properties":{"code":{"type":"string","description":"Alert identifier.","enum":["SDK_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","BACKEND1N_OPERATION_FAILED","IDLE"]},"severity":{"type":"string","description":"Severity of the alert.","enum":["critical","warning","info"]},"message":{"type":"string","description":"Human-readable description of the reason for the alert."},"since":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The MetricsSdkState object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MetricsSdkState":{"type":"object","description":"Last known health snapshot of the SDK. The values are published from that cached snapshot and never from an active check, so that the endpoint remains cheap to query on every scrape.\n","properties":{"initialized":{"type":"boolean"},"alive":{"type":"boolean"},"healthy":{"type":"boolean"},"lastInitStatus":{"type":"string","description":"Status returned by the SDK when the service started."},"lastHealthKnown":{"type":"boolean","description":"If false, no health check has been recorded yet."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string when there is none."}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The MetricsState object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"MetricsState":{"type":"object","description":"Service state summarized from the snapshot.","properties":{"initialized":{"type":"boolean","description":"Whether the SDK started correctly when the service started."},"classification":{"$ref":"#/components/schemas/MetricsClassification"},"sdk":{"$ref":"#/components/schemas/MetricsSdkState"}}},"MetricsClassification":{"type":"string","description":"Summary of the operational state of the service, derived solely from the published snapshot. The rules are evaluated in this order and the first one that is met wins: `unhealthy` (the SDK did not start or the last known health check is negative), `saturated`, `degraded`, `unknown` (no request has been served yet and health has not been checked), `idle` and `ok`. The numeric thresholds are the `metrics_*` parameters described in the installation manual.\n","enum":["ok","degraded","saturated","idle","unhealthy","unknown"]},"MetricsSdkState":{"type":"object","description":"Last known health snapshot of the SDK. The values are published from that cached snapshot and never from an active check, so that the endpoint remains cheap to query on every scrape.\n","properties":{"initialized":{"type":"boolean"},"alive":{"type":"boolean"},"healthy":{"type":"boolean"},"lastInitStatus":{"type":"string","description":"Status returned by the SDK when the service started."},"lastHealthKnown":{"type":"boolean","description":"If false, no health check has been recorded yet."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string when there is none."}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."}}}}
```

## The OperationalMetricsResponse object

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"components":{"schemas":{"OperationalMetricsResponse":{"type":"object","description":"Operational snapshot of the service. It is built solely from state that is already in memory - it does not query the SDK or the database -, so it can be queried every few seconds without penalizing the service. The `traffic`, `saturation` and `latency` blocks are collected by the REST manager; `service`, `state`, `usage`, `quality` and `alerts` are added by Backend1N Service.\n","properties":{"schemaVersion":{"type":"string","description":"Version of this snapshot's contract."},"timestamp":{"$ref":"#/components/schemas/TimeStamp"},"service":{"type":"object","additionalProperties":true,"description":"Identity of the service - `name`, `version`, `pathBase`, `uptimeSeconds` and `configuredThreads`."},"state":{"$ref":"#/components/schemas/MetricsState"},"traffic":{"type":"object","additionalProperties":true,"description":"Cumulative totals (`requests`, `success`, `clientErrors`, `serverErrors`, `unauthorized`; disjoint categories that add up to `requests`), windows of `1m`, `5m` and `15m` with `requests`, `rps`, `successRate` and `errorRate`, and the `byEndpoint` breakdown with the same counters per registered route. Routes are published as a template with the parameters named `{uuid}` (`/faces/{uuid}`, `/assets/media/{uuid}`) and `{collectionId}`.\n"},"saturation":{"type":"object","additionalProperties":true,"description":"`inflight`, `maxInflight1m`, `configuredThreads`, `queueP95Ms1m` and `backlogSuspected`."},"latency":{"type":"object","additionalProperties":true,"description":"Latency in milliseconds per window (`1m`, `5m`, `15m`), split into `totalMs`, `queueMs` (time in queue) and `sdkMs` (time inside the SDK). Each one publishes `avg`, `p50`, `p95`, `p99` and `max`. The percentiles are approximate (computed by intervals), so they may coincide with the interval edge and end up above the observed maximum when there are few samples.\n"},"usage":{"type":"object","additionalProperties":true,"description":"Request counters per business operation in `operations`, keyed as `METHOD /path`. The management routes (`/health`, `/version`, `/config`, `/metrics` and `/metrics/prometheus`) are excluded.\n"},"quality":{"type":"object","additionalProperties":true,"description":"Aggregated signals for `extraction`, `search` and `database`, plus `lastFailure` with the code and the time of the last failed operation (empty object while none has failed). It only contains aggregates: no biometric template, image, identifier or personal data is stored. The score summaries (`faceConfidence`, `imageQuality`, `bestSimilarity`) publish `count`, `min`, `max`, `avg`, `p50` and `p95`.\n"},"alerts":{"type":"array","description":"Actionable alerts. Empty list when there is nothing to report.","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."},"MetricsState":{"type":"object","description":"Service state summarized from the snapshot.","properties":{"initialized":{"type":"boolean","description":"Whether the SDK started correctly when the service started."},"classification":{"$ref":"#/components/schemas/MetricsClassification"},"sdk":{"$ref":"#/components/schemas/MetricsSdkState"}}},"MetricsClassification":{"type":"string","description":"Summary of the operational state of the service, derived solely from the published snapshot. The rules are evaluated in this order and the first one that is met wins: `unhealthy` (the SDK did not start or the last known health check is negative), `saturated`, `degraded`, `unknown` (no request has been served yet and health has not been checked), `idle` and `ok`. The numeric thresholds are the `metrics_*` parameters described in the installation manual.\n","enum":["ok","degraded","saturated","idle","unhealthy","unknown"]},"MetricsSdkState":{"type":"object","description":"Last known health snapshot of the SDK. The values are published from that cached snapshot and never from an active check, so that the endpoint remains cheap to query on every scrape.\n","properties":{"initialized":{"type":"boolean"},"alive":{"type":"boolean"},"healthy":{"type":"boolean"},"lastInitStatus":{"type":"string","description":"Status returned by the SDK when the service started."},"lastHealthKnown":{"type":"boolean","description":"If false, no health check has been recorded yet."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string when there is none."}}},"MetricsAlert":{"type":"object","description":"Actionable alert derived from the snapshot.","properties":{"code":{"type":"string","description":"Alert identifier.","enum":["SDK_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","BACKEND1N_OPERATION_FAILED","IDLE"]},"severity":{"type":"string","description":"Severity of the alert.","enum":["critical","warning","info"]},"message":{"type":"string","description":"Human-readable description of the reason for the alert."},"since":{"$ref":"#/components/schemas/TimeStamp"}}}}}}
```