> 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/finger/technical_documentation/api_reference/models.md).

# Models

## The TimeStamp object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."}}}}
```

## The MessageResult object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MessageResult":{"type":"object","properties":{"message":{"type":"string","description":"Service message."}},"required":["message"]}}}}
```

## The VersionResult object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"VersionResult":{"type":"object","properties":{"message":{"type":"string","description":"`<version> Copyright © <year> FacePhi Biometria. All rights reserved.` When the license is not valid, the\ntext `. Invalid license: <reason> (code: <code>)` is appended.\n"}},"required":["message"]}}}}
```

## The LicenseStatus object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"LicenseStatus":{"type":"object","description":"Status of the service license.","properties":{"valid":{"type":"boolean","description":"Whether the service currently holds a valid license. This is the field to check."},"statusCode":{"type":"string","description":"Status code reported by the licensing layer, for example `LA_OK`, `LF_OK`, `OK` or an error code."},"statusMessage":{"type":"string","description":"Human-readable description of `statusCode`. `The license is valid.` when the license is valid."}},"required":["valid","statusCode","statusMessage"]}}}}
```

## The FingerPosition object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]}}}}
```

## The ScanType object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ScanType":{"type":"string","description":"Capture type of the fingerprint image.","enum":["Plain","Rolled","Latent"]}}}}
```

## The HealthEngine object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"HealthEngine":{"type":"object","description":"State of the internal fingerprint processing components, as observed by the last health check. On `master`\nnodes the check asks the processing components whether all of them are registered; on `worker` nodes it\nchecks that every locally configured processing service is accepting connections.\n","properties":{"initialized":{"type":"boolean","description":"Always `true` once the service is initialized."},"healthy":{"type":"boolean","description":"Result of the last health check. `false` until the first check runs."},"role":{"type":"string","description":"Node role (`master` or `worker`).","enum":["master","worker"]},"lastHealthKnown":{"type":"boolean","description":"Whether a health check has already run since the service started."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last health check (`YYYY-MM-DDTHH:MM:SSZ`); empty until the first check runs."},"lastError":{"type":"string","description":"Reason of the last failed health check; empty when the last check succeeded."},"servicesConfigured":{"type":"array","description":"Processing services configured on this node (`FACEPHI_FINGER_ENGINE_SERVICES`).","items":{"type":"string"}}},"required":["initialized","healthy","role","lastHealthKnown","lastHealthCheckAt","lastError","servicesConfigured"]}}}}
```

## The HealthResponse object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"message":{"type":"string","description":"`Healthy` when the license is valid and the last health check succeeded; `Unhealthy` otherwise. The\nresponse is always HTTP `200`: check `message`, `license.valid` and `engine.healthy`.\n","enum":["Healthy","Unhealthy"]},"initialized":{"type":"boolean","description":"Always `true` once the service is initialized."},"license":{"$ref":"#/components/schemas/LicenseStatus"},"engine":{"$ref":"#/components/schemas/HealthEngine"}},"required":["message","initialized","license","engine"]},"LicenseStatus":{"type":"object","description":"Status of the service license.","properties":{"valid":{"type":"boolean","description":"Whether the service currently holds a valid license. This is the field to check."},"statusCode":{"type":"string","description":"Status code reported by the licensing layer, for example `LA_OK`, `LF_OK`, `OK` or an error code."},"statusMessage":{"type":"string","description":"Human-readable description of `statusCode`. `The license is valid.` when the license is valid."}},"required":["valid","statusCode","statusMessage"]},"HealthEngine":{"type":"object","description":"State of the internal fingerprint processing components, as observed by the last health check. On `master`\nnodes the check asks the processing components whether all of them are registered; on `worker` nodes it\nchecks that every locally configured processing service is accepting connections.\n","properties":{"initialized":{"type":"boolean","description":"Always `true` once the service is initialized."},"healthy":{"type":"boolean","description":"Result of the last health check. `false` until the first check runs."},"role":{"type":"string","description":"Node role (`master` or `worker`).","enum":["master","worker"]},"lastHealthKnown":{"type":"boolean","description":"Whether a health check has already run since the service started."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last health check (`YYYY-MM-DDTHH:MM:SSZ`); empty until the first check runs."},"lastError":{"type":"string","description":"Reason of the last failed health check; empty when the last check succeeded."},"servicesConfigured":{"type":"array","description":"Processing services configured on this node (`FACEPHI_FINGER_ENGINE_SERVICES`).","items":{"type":"string"}}},"required":["initialized","healthy","role","lastHealthKnown","lastHealthCheckAt","lastError","servicesConfigured"]}}}}
```

## The ConfigData object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ConfigData":{"type":"object","description":"Public view of the runtime configuration. Every value is returned as a string. It contains the REST\nparameters with their default value or the one set in `config.json`, plus any other parameter defined in\n`config.json` or sent to `POST /api/v1/finger/config`. It does not reflect values set through environment\nvariables. JWT authentication settings (`auth_*`) are always omitted.\n","additionalProperties":{"type":"string"}}}}}
```

## The ConfigUpdateRequest object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ConfigUpdateRequest":{"type":"object","required":["config_json_string"],"properties":{"config_json_string":{"type":"string","description":"Parameters to change, serialized as a JSON object inside a string. Parameters that are not included keep\ntheir current value. JWT authentication settings (`auth_*`) are rejected.\n"}}}}}}
```

## The ExtractOptions object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ExtractOptions":{"type":"object","description":"Optional tuning parameters of the extraction.","properties":{"dpi":{"type":"integer","description":"Resolution of the fingerprint image in dots per inch.","minimum":250,"maximum":1000,"default":500},"scanType":{"$ref":"#/components/schemas/ScanType"},"includeQuality":{"type":"boolean","description":"When `false`, the response omits `quality` and `qualityDetails`, and the extraction is not taken into\naccount in the quality figures of `GET /api/v1/finger/metrics`.\n","default":true}}},"ScanType":{"type":"string","description":"Capture type of the fingerprint image.","enum":["Plain","Rolled","Latent"]}}}}
```

## The ExtractRequest object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ExtractRequest":{"type":"object","required":["image","position"],"properties":{"image":{"type":"string","description":"Fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"position":{"$ref":"#/components/schemas/FingerPosition"},"options":{"$ref":"#/components/schemas/ExtractOptions"}}},"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]},"ExtractOptions":{"type":"object","description":"Optional tuning parameters of the extraction.","properties":{"dpi":{"type":"integer","description":"Resolution of the fingerprint image in dots per inch.","minimum":250,"maximum":1000,"default":500},"scanType":{"$ref":"#/components/schemas/ScanType"},"includeQuality":{"type":"boolean","description":"When `false`, the response omits `quality` and `qualityDetails`, and the extraction is not taken into\naccount in the quality figures of `GET /api/v1/finger/metrics`.\n","default":true}}},"ScanType":{"type":"string","description":"Capture type of the fingerprint image.","enum":["Plain","Rolled","Latent"]}}}}
```

## The QualityDetails object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"QualityDetails":{"type":"object","description":"Detailed quality figures. Each field is only present when the processing components report it.","properties":{"nfiq2":{"type":"number","format":"float","description":"NFIQ 2 quality score, on a 0-100 scale where a higher value means a better capture."},"nfiq":{"type":"number","format":"float","description":"NFIQ quality level."},"score":{"type":"number","format":"float","description":"Quality score of the fingerprint."}}}}}}
```

## The ExtractResponse object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ExtractResponse":{"type":"object","description":"Public extract response.","required":["fingerTemplate","position","scanType","sdkDuration","queueDuration"],"properties":{"fingerTemplate":{"type":"string","description":"Generated fingerprint template, encoded in Base64. Use it as `fingerTemplate1` or `fingerTemplate2` in `POST /api/v1/finger/authenticate`."},"position":{"$ref":"#/components/schemas/FingerPosition"},"scanType":{"$ref":"#/components/schemas/ScanType"},"quality":{"type":"integer","description":"Overall quality score (0-100, higher is better). Present when the processing components report it and\n`options.includeQuality` is not `false`.\n"},"qualityDetails":{"$ref":"#/components/schemas/QualityDetails"},"sdkDuration":{"type":"integer","format":"int64","description":"Processing time in milliseconds."},"queueDuration":{"type":"integer","format":"int64","description":"Time the request waited in the queue, in milliseconds."}}},"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]},"ScanType":{"type":"string","description":"Capture type of the fingerprint image.","enum":["Plain","Rolled","Latent"]},"QualityDetails":{"type":"object","description":"Detailed quality figures. Each field is only present when the processing components report it.","properties":{"nfiq2":{"type":"number","format":"float","description":"NFIQ 2 quality score, on a 0-100 scale where a higher value means a better capture."},"nfiq":{"type":"number","format":"float","description":"NFIQ quality level."},"score":{"type":"number","format":"float","description":"Quality score of the fingerprint."}}}}}}
```

## The AuthenticateOptions object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"AuthenticateOptions":{"type":"object","description":"Optional tuning parameters of the authentication.","properties":{"dpi":{"type":"integer","description":"Resolution, in dots per inch, of the images sent in `image1` and `image2`.","minimum":250,"maximum":1000,"default":500},"authThreshold":{"type":"integer","description":"Minimum `similarity` for `authStatus` to be `Positive`. It must be an integer between 0 and 100; decimal\nvalues are rejected.\n","minimum":0,"maximum":100,"default":20}}}}}}
```

## The AuthenticateRequest object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"AuthenticateRequest":{"type":"object","description":"Public 1:1 authentication request. Exactly one source is required on each side:\n\n- Side 1 (probe): `image1` or `fingerTemplate1`\n- Side 2 (gallery): `image2` or `fingerTemplate2`\n\nImages and templates can be combined (for example, `image1` with `fingerTemplate2`). The finger position is\ngiven either as a shared `position` or per side with `position1` and `position2`, which take precedence over\n`position` for their side.\n","properties":{"image1":{"type":"string","description":"Probe fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"fingerTemplate1":{"type":"string","description":"Probe fingerprint template encoded in Base64, as returned by `POST /api/v1/finger/extract`."},"image2":{"type":"string","description":"Gallery fingerprint image encoded in Base64 (RFC 4648). Supported formats; wsq, bmp, png, jpg, jp2."},"fingerTemplate2":{"type":"string","description":"Gallery fingerprint template encoded in Base64, as returned by `POST /api/v1/finger/extract`."},"position":{"$ref":"#/components/schemas/FingerPosition"},"position1":{"$ref":"#/components/schemas/FingerPosition"},"position2":{"$ref":"#/components/schemas/FingerPosition"},"options":{"$ref":"#/components/schemas/AuthenticateOptions"}}},"FingerPosition":{"type":"string","description":"Public finger position name.","enum":["RightThumb","RightIndex","RightMiddle","RightRing","RightLittle","LeftThumb","LeftIndex","LeftMiddle","LeftRing","LeftLittle"]},"AuthenticateOptions":{"type":"object","description":"Optional tuning parameters of the authentication.","properties":{"dpi":{"type":"integer","description":"Resolution, in dots per inch, of the images sent in `image1` and `image2`.","minimum":250,"maximum":1000,"default":500},"authThreshold":{"type":"integer","description":"Minimum `similarity` for `authStatus` to be `Positive`. It must be an integer between 0 and 100; decimal\nvalues are rejected.\n","minimum":0,"maximum":100,"default":20}}}}}}
```

## The AuthenticateResponse object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"AuthenticateResponse":{"type":"object","description":"Public 1:1 authentication response.","required":["authStatus","similarity","sdkDuration","queueDuration"],"properties":{"authStatus":{"type":"string","description":"`Positive` when `similarity` is greater than or equal to `options.authThreshold`, `Negative` otherwise.\nA `Negative` result is a successful authentication (HTTP `200`), not an error.\n","enum":["Positive","Negative"]},"similarity":{"type":"number","format":"float","description":"Similarity score between both fingerprints, in the 0-100 range.","minimum":0,"maximum":100},"sdkDuration":{"type":"integer","format":"int64","description":"Processing time in milliseconds."},"queueDuration":{"type":"integer","format":"int64","description":"Time the request waited in the queue, in milliseconds."}}}}}}
```

## The MetricsService object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsService":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"role":{"type":"string","enum":["master","worker"]},"pathBase":{"type":"string"},"configuredThreads":{"type":"integer","description":"Configured worker threads (`number_of_threads`)."}}}}}}
```

## The MetricsEngineState object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsEngineState":{"type":"object","description":"Result of the last call to `GET /api/v1/finger/health`. `/metrics` never runs a health check itself.","properties":{"role":{"type":"string"},"servicesConfigured":{"type":"array","items":{"type":"string"}},"healthy":{"type":"boolean"},"lastHealthKnown":{"type":"boolean"},"lastHealthCheckAt":{"type":"string"},"lastError":{"type":"string"}}}}}}
```

## The MetricsState object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsState":{"type":"object","properties":{"initialized":{"type":"boolean"},"license":{"$ref":"#/components/schemas/LicenseStatus"},"engine":{"$ref":"#/components/schemas/MetricsEngineState"},"classification":{"type":"string","description":"Single-value summary of the snapshot. The cases are evaluated in this order and the first one that\nmatches applies:\n\n| Value | When |\n|---|---|\n| `unhealthy` | The service is not initialized, the license is not valid, or the last health check failed |\n| `unknown` | There is no traffic yet, no health check has run and there is no quality alert |\n| `saturated` | There is traffic and either `saturation.backlogSuspected` is `true`, or in-flight requests exceed `metrics_saturation_min_inflight_ratio` times the configured threads while the 1-minute queue p95 reaches `metrics_saturation_queue_p95_ms` |\n| `degraded` | The 5-minute error rate (`4xx` and `5xx`) reaches `metrics_error_rate_warning`, there has been at least one server error (`5xx`) since startup, or the `LOW_QUALITY` alert is active |\n| `idle` | There is traffic, the 15-minute request rate is below `metrics_idle_rps_threshold` and no backlog is suspected |\n| `ok` | None of the above |\n","enum":["ok","idle","degraded","saturated","unhealthy","unknown"]}}},"LicenseStatus":{"type":"object","description":"Status of the service license.","properties":{"valid":{"type":"boolean","description":"Whether the service currently holds a valid license. This is the field to check."},"statusCode":{"type":"string","description":"Status code reported by the licensing layer, for example `LA_OK`, `LF_OK`, `OK` or an error code."},"statusMessage":{"type":"string","description":"Human-readable description of `statusCode`. `The license is valid.` when the license is valid."}},"required":["valid","statusCode","statusMessage"]},"MetricsEngineState":{"type":"object","description":"Result of the last call to `GET /api/v1/finger/health`. `/metrics` never runs a health check itself.","properties":{"role":{"type":"string"},"servicesConfigured":{"type":"array","items":{"type":"string"}},"healthy":{"type":"boolean"},"lastHealthKnown":{"type":"boolean"},"lastHealthCheckAt":{"type":"string"},"lastError":{"type":"string"}}}}}}
```

## The TrafficCounters object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"success":{"type":"integer","format":"int64"},"clientErrors":{"type":"integer","format":"int64"},"serverErrors":{"type":"integer","format":"int64"},"unauthorized":{"type":"integer","format":"int64"}}}}}}
```

## The TrafficWindow object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"rps":{"type":"number","format":"double"},"successRate":{"type":"number","format":"double"},"errorRate":{"type":"number","format":"double","description":"Ratio of `4xx` and `5xx` responses in the window."}}}}}}
```

## The TrafficEndpoint object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"TrafficEndpoint":{"allOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}},{"$ref":"#/components/schemas/TrafficCounters"}]},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"success":{"type":"integer","format":"int64"},"clientErrors":{"type":"integer","format":"int64"},"serverErrors":{"type":"integer","format":"int64"},"unauthorized":{"type":"integer","format":"int64"}}}}}}
```

## The MetricsTraffic object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsTraffic":{"type":"object","description":"Every request served since startup, management endpoints included.","properties":{"totals":{"$ref":"#/components/schemas/TrafficCounters"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/TrafficWindow"},"5m":{"$ref":"#/components/schemas/TrafficWindow"},"15m":{"$ref":"#/components/schemas/TrafficWindow"}}},"byEndpoint":{"type":"array","description":"One entry per endpoint that has already received requests.","items":{"$ref":"#/components/schemas/TrafficEndpoint"}}}},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"success":{"type":"integer","format":"int64"},"clientErrors":{"type":"integer","format":"int64"},"serverErrors":{"type":"integer","format":"int64"},"unauthorized":{"type":"integer","format":"int64"}}},"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"rps":{"type":"number","format":"double"},"successRate":{"type":"number","format":"double"},"errorRate":{"type":"number","format":"double","description":"Ratio of `4xx` and `5xx` responses in the window."}}},"TrafficEndpoint":{"allOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}},{"$ref":"#/components/schemas/TrafficCounters"}]}}}}
```

## The MetricsSaturation object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsSaturation":{"type":"object","properties":{"inflight":{"type":"integer","format":"int64"},"maxInflight1m":{"type":"integer","format":"int64"},"configuredThreads":{"type":"integer","format":"int64"},"queueP95Ms1m":{"type":"integer","format":"int64"},"backlogSuspected":{"type":"boolean"}}}}}}
```

## The LatencyStats object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"LatencyStats":{"type":"object","properties":{"avg":{"type":"integer","format":"int64"},"p50":{"type":"integer","format":"int64"},"p95":{"type":"integer","format":"int64"},"p99":{"type":"integer","format":"int64"},"max":{"type":"integer","format":"int64"}}}}}}
```

## The LatencyWindow object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","properties":{"avg":{"type":"integer","format":"int64"},"p50":{"type":"integer","format":"int64"},"p95":{"type":"integer","format":"int64"},"p99":{"type":"integer","format":"int64"},"max":{"type":"integer","format":"int64"}}}}}}
```

## The MetricsLatency object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsLatency":{"type":"object","properties":{"scope":{"type":"string"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/LatencyWindow"},"5m":{"$ref":"#/components/schemas/LatencyWindow"},"15m":{"$ref":"#/components/schemas/LatencyWindow"}}}}},"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","properties":{"avg":{"type":"integer","format":"int64"},"p50":{"type":"integer","format":"int64"},"p95":{"type":"integer","format":"int64"},"p99":{"type":"integer","format":"int64"},"max":{"type":"integer","format":"int64"}}}}}}
```

## The MetricsUsage object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsUsage":{"type":"object","description":"Usage counters of the license for the fingerprint operations completed successfully. They are the values\naccumulated by the license, including the increments of this instance that are still pending\nsynchronization, so they are not reset when the service restarts.\n","properties":{"enabled":{"type":"boolean","description":"Whether the license enables usage counters. When `false`, the counters stay at `0`."},"operations":{"type":"object","properties":{"extract":{"type":"integer","format":"int64"},"authenticate":{"type":"integer","format":"int64"}}},"total":{"type":"integer","format":"int64","description":"`operations.extract` + `operations.authenticate`."}}}}}}
```

## The NumericSummary object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"NumericSummary":{"type":"object","properties":{"samples":{"type":"integer","format":"int64"},"avg":{"type":"number","format":"double"},"min":{"type":"number","format":"double"},"max":{"type":"number","format":"double"}}}}}}
```

## The MetricsQuality object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsQuality":{"type":"object","description":"Quality figures aggregated since startup from the successful fingerprint operations. It is an empty object\nuntil the first successful operation. `extract` appears with the first successful extraction, `authenticate`\nwith the first successful authentication, and `summary` as soon as the block is not empty.\n","properties":{"extract":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful extractions."},"measuredSamples":{"type":"integer","format":"int64","description":"Extractions that returned `quality` or `qualityDetails.nfiq2`."},"overallQuality":{"$ref":"#/components/schemas/NumericSummary"},"nfiq2":{"$ref":"#/components/schemas/NumericSummary"}}},"authenticate":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful authentications."},"positive":{"type":"integer","format":"int64"},"negative":{"type":"integer","format":"int64"},"similarity":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","format":"int64","description":"Extractions whose `quality` or `qualityDetails.nfiq2` was below 50."},"lowQualitySince":{"type":"string","description":"UTC instant of the first low-quality extraction since startup; only present once there is one."}}}}},"NumericSummary":{"type":"object","properties":{"samples":{"type":"integer","format":"int64"},"avg":{"type":"number","format":"double"},"min":{"type":"number","format":"double"},"max":{"type":"number","format":"double"}}}}}}
```

## The MetricsAlert object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant (`YYYY-MM-DDTHH:MM:SSZ`). For `ENGINE_UNAVAILABLE` it is the instant of the failed health\ncheck, for `LOW_QUALITY` the start of the current low-quality episode, and for the other alerts the instant\nof the snapshot.\n"}}}}}}
```

## The MetricsResponse object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"MetricsResponse":{"type":"object","description":"Operational metrics snapshot. See the operation description for the meaning of each block.","properties":{"schemaVersion":{"type":"string"},"timestamp":{"type":"string","description":"UTC instant of the snapshot (`YYYY-MM-DDTHH:MM:SSZ`)."},"service":{"$ref":"#/components/schemas/MetricsService"},"state":{"$ref":"#/components/schemas/MetricsState"},"traffic":{"$ref":"#/components/schemas/MetricsTraffic"},"saturation":{"$ref":"#/components/schemas/MetricsSaturation"},"latency":{"$ref":"#/components/schemas/MetricsLatency"},"usage":{"$ref":"#/components/schemas/MetricsUsage"},"usageCountersEnabled":{"type":"boolean","description":"Same value as `usage.enabled`, kept for compatibility with 2.1.0."},"extractCount":{"type":"integer","format":"int64","description":"Same value as `usage.operations.extract`, kept for compatibility with 2.1.0."},"authenticateCount":{"type":"integer","format":"int64","description":"Same value as `usage.operations.authenticate`, kept for compatibility with 2.1.0."},"totalCount":{"type":"integer","format":"int64","description":"Same value as `usage.total`, kept for compatibility with 2.1.0."},"quality":{"$ref":"#/components/schemas/MetricsQuality"},"alerts":{"type":"array","description":"Active alerts; empty when there are none.","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"MetricsService":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"role":{"type":"string","enum":["master","worker"]},"pathBase":{"type":"string"},"configuredThreads":{"type":"integer","description":"Configured worker threads (`number_of_threads`)."}}},"MetricsState":{"type":"object","properties":{"initialized":{"type":"boolean"},"license":{"$ref":"#/components/schemas/LicenseStatus"},"engine":{"$ref":"#/components/schemas/MetricsEngineState"},"classification":{"type":"string","description":"Single-value summary of the snapshot. The cases are evaluated in this order and the first one that\nmatches applies:\n\n| Value | When |\n|---|---|\n| `unhealthy` | The service is not initialized, the license is not valid, or the last health check failed |\n| `unknown` | There is no traffic yet, no health check has run and there is no quality alert |\n| `saturated` | There is traffic and either `saturation.backlogSuspected` is `true`, or in-flight requests exceed `metrics_saturation_min_inflight_ratio` times the configured threads while the 1-minute queue p95 reaches `metrics_saturation_queue_p95_ms` |\n| `degraded` | The 5-minute error rate (`4xx` and `5xx`) reaches `metrics_error_rate_warning`, there has been at least one server error (`5xx`) since startup, or the `LOW_QUALITY` alert is active |\n| `idle` | There is traffic, the 15-minute request rate is below `metrics_idle_rps_threshold` and no backlog is suspected |\n| `ok` | None of the above |\n","enum":["ok","idle","degraded","saturated","unhealthy","unknown"]}}},"LicenseStatus":{"type":"object","description":"Status of the service license.","properties":{"valid":{"type":"boolean","description":"Whether the service currently holds a valid license. This is the field to check."},"statusCode":{"type":"string","description":"Status code reported by the licensing layer, for example `LA_OK`, `LF_OK`, `OK` or an error code."},"statusMessage":{"type":"string","description":"Human-readable description of `statusCode`. `The license is valid.` when the license is valid."}},"required":["valid","statusCode","statusMessage"]},"MetricsEngineState":{"type":"object","description":"Result of the last call to `GET /api/v1/finger/health`. `/metrics` never runs a health check itself.","properties":{"role":{"type":"string"},"servicesConfigured":{"type":"array","items":{"type":"string"}},"healthy":{"type":"boolean"},"lastHealthKnown":{"type":"boolean"},"lastHealthCheckAt":{"type":"string"},"lastError":{"type":"string"}}},"MetricsTraffic":{"type":"object","description":"Every request served since startup, management endpoints included.","properties":{"totals":{"$ref":"#/components/schemas/TrafficCounters"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/TrafficWindow"},"5m":{"$ref":"#/components/schemas/TrafficWindow"},"15m":{"$ref":"#/components/schemas/TrafficWindow"}}},"byEndpoint":{"type":"array","description":"One entry per endpoint that has already received requests.","items":{"$ref":"#/components/schemas/TrafficEndpoint"}}}},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"success":{"type":"integer","format":"int64"},"clientErrors":{"type":"integer","format":"int64"},"serverErrors":{"type":"integer","format":"int64"},"unauthorized":{"type":"integer","format":"int64"}}},"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"rps":{"type":"number","format":"double"},"successRate":{"type":"number","format":"double"},"errorRate":{"type":"number","format":"double","description":"Ratio of `4xx` and `5xx` responses in the window."}}},"TrafficEndpoint":{"allOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}},{"$ref":"#/components/schemas/TrafficCounters"}]},"MetricsSaturation":{"type":"object","properties":{"inflight":{"type":"integer","format":"int64"},"maxInflight1m":{"type":"integer","format":"int64"},"configuredThreads":{"type":"integer","format":"int64"},"queueP95Ms1m":{"type":"integer","format":"int64"},"backlogSuspected":{"type":"boolean"}}},"MetricsLatency":{"type":"object","properties":{"scope":{"type":"string"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/LatencyWindow"},"5m":{"$ref":"#/components/schemas/LatencyWindow"},"15m":{"$ref":"#/components/schemas/LatencyWindow"}}}}},"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","properties":{"avg":{"type":"integer","format":"int64"},"p50":{"type":"integer","format":"int64"},"p95":{"type":"integer","format":"int64"},"p99":{"type":"integer","format":"int64"},"max":{"type":"integer","format":"int64"}}},"MetricsUsage":{"type":"object","description":"Usage counters of the license for the fingerprint operations completed successfully. They are the values\naccumulated by the license, including the increments of this instance that are still pending\nsynchronization, so they are not reset when the service restarts.\n","properties":{"enabled":{"type":"boolean","description":"Whether the license enables usage counters. When `false`, the counters stay at `0`."},"operations":{"type":"object","properties":{"extract":{"type":"integer","format":"int64"},"authenticate":{"type":"integer","format":"int64"}}},"total":{"type":"integer","format":"int64","description":"`operations.extract` + `operations.authenticate`."}}},"MetricsQuality":{"type":"object","description":"Quality figures aggregated since startup from the successful fingerprint operations. It is an empty object\nuntil the first successful operation. `extract` appears with the first successful extraction, `authenticate`\nwith the first successful authentication, and `summary` as soon as the block is not empty.\n","properties":{"extract":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful extractions."},"measuredSamples":{"type":"integer","format":"int64","description":"Extractions that returned `quality` or `qualityDetails.nfiq2`."},"overallQuality":{"$ref":"#/components/schemas/NumericSummary"},"nfiq2":{"$ref":"#/components/schemas/NumericSummary"}}},"authenticate":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful authentications."},"positive":{"type":"integer","format":"int64"},"negative":{"type":"integer","format":"int64"},"similarity":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","format":"int64","description":"Extractions whose `quality` or `qualityDetails.nfiq2` was below 50."},"lowQualitySince":{"type":"string","description":"UTC instant of the first low-quality extraction since startup; only present once there is one."}}}}},"NumericSummary":{"type":"object","properties":{"samples":{"type":"integer","format":"int64"},"avg":{"type":"number","format":"double"},"min":{"type":"number","format":"double"},"max":{"type":"number","format":"double"}}},"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant (`YYYY-MM-DDTHH:MM:SSZ`). For `ENGINE_UNAVAILABLE` it is the instant of the failed health\ncheck, for `LOW_QUALITY` the start of the current low-quality episode, and for the other alerts the instant\nof the snapshot.\n"}}}}}}
```

## The BadRequestResult object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"BadRequestResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."}}}}
```

## The UnauthorizedResult object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"UnauthorizedResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."}}}}
```

## The ExceptionResult object

```json
{"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"components":{"schemas":{"ExceptionResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"exception":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","exception","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."}}}}
```