Skip to main content

# API Requests for Working with Attempts

## Request for Getting a List of Attempts​

This request returns a paginated list of attempts (endeavors) filtered by external links. Filtering by the creation time range is supported. Results are sorted by creation time; the sort order can be changed.

Request schema:
`GET /lrs/endeavor?sort_order={sort_order}&page={page_number}&page_size={page_size}`

### Query Parameters​

Parameter | Description
--- | ---
`sort_order` | Sort order by creation time. Possible values: `asc` (ascending), `desc` (descending). Required.
`page` | Page number to request. Minimum value: `1`. Required.
`page_size` | Number of items per page. Allowed range: 1 to 100. Required.
`external_link` | Filter by external link. If not specified, returns all attempts with `external_link` equal to `null`.
`start_date` | Lower bound of the creation time range (inclusive).
`end_date` | Upper bound of the creation time range (exclusive).

### Request Headers​

Header | Description
--- | ---
`token` | Token of the `video-recorder` service. Stored in the `video-recorder-token` secret in the `./cfg/video-recorder.secrets.json` file.

### Example Request​

    curl -X 'GET' \
      'http://192.168.10.1/lrs/endeavor?sort_order=asc&page=1&page_size=1' \
      -H 'accept: application/json' \
      -H 'token: token'

### Example Response​

    {
      "page": 1,
      "page_size": 1,
      "total_count": 8,
      "endeavor_list": [
        {
          "id": "e4823024-d578-4285-9d3b-0471a4f720b2",
          "external_link": null,
          "content": [
            {
              "id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
              "files": [
                {
                  "s3_link": "lr.videos:motion_control_video-26-07-06-12_38_10-no-parent-e4823-5e77c.webm",
                  "raw_data_in_base64": null
                }
              ],
              "type": 1,
              "parent_id": null,
              "info": {
                "motion_control_result": [
                  { "result": true, "pattern": "right" },
                  { "result": true, "pattern": "left" },
                  { "result": true, "pattern": "left" }
                ]
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:10.960546Z",
              "last_modified": "2026-07-06T12:38:10.960546Z"
            },
            {
              "id": "ac16bccc-478e-48ec-80e6-7cd0666a5e83",
              "files": [
                {
                  "s3_link": "lr.ref-images:reference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg",
                  "raw_data_in_base64": null
                }
              ],
              "type": 3,
              "parent_id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
              "info": {
                "angles": [0, -2],
                "image_info": {
                  "quality": {
                    "value": true,
                    "failed_checks": null
                  },
                  "deepfake": {
                    "confidence": 0.00021070241928100586
                  },
                  "liveness": {
                    "value": "real",
                    "confidence": 0.9773591756820679,
                    "attack_type": "none",
                    "attack_type_scores": {
                      "none": 0.9773591756820679,
                      "photo": 0.0008513810934558892,
                      "replay": 0.007360487079161384,
                      "2d_mask": 0.0008028665221645174,
                      "3d_mask": 0.0017056756156491595,
                      "regions": 0.011920414007501181
                    }
                  }
                },
                "frame_number": 128
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:10.960546Z",
              "last_modified": "2026-07-06T12:38:10.960546Z"
            },
            {
              "id": "ce79a10b-26c1-4ccb-9c21-6f5439569a77",
              "files": [],
              "type": 5,
              "parent_id": null,
              "info": {
                "verification_info": {
                  "fa_r": 0,
                  "fr_r": 0.6750852465629578,
                  "score": 0.9856855273246765,
                  "distance": 2339
                }
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:12.671648Z",
              "last_modified": "2026-07-06T12:38:12.671648Z"
            }
          ],
          "creation_date": "2026-07-06T12:37:58.219058Z",
          "last_modified": "2026-07-06T12:37:58.219058Z"
        }
      ]
    }

The response contains the following fields:

Field | Description
--- | ---
`page` | Current page number (matches the one in the request).
`page_size` | Number of items per page (matches the request).
`total_count` | Total number of attempts matching the filter criteria.
`endeavor_list` | Array of attempts on the current page. For details on the attempt object, see the Attempt Object Structure section.

## Request for Getting a Specific Attempt by ID​

This request returns an attempt by its ID. The attempt ID can be obtained from web component callbacks.

Request schema:
`GET /lrs/endeavor/{endeavor_id}`

### Request Headers​

Header | Description
--- | ---
`token` | Token of the `video-recorder` service. Stored in the `video-recorder-token` secret in the `./cfg/video-recorder.secrets.json` file.

### Example Request​

    curl -X 'GET' \
      'http://192.168.10.1/lrs/endeavor/e4823024-d578-4285-9d3b-0471a4f720b2' \
      -H 'accept: application/json' \
      -H 'token: token'

### Example Response​

    {
      "id": "e4823024-d578-4285-9d3b-0471a4f720b2",
      "external_link": null,
      "content": [
        {
          "id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
          "files": [
            {
              "s3_link": "lr.videos:motion_control_video-26-07-06-12_38_10-no-parent-e4823-5e77c.webm",
              "raw_data_in_base64": null
            }
          ],
          "type": 1,
          "parent_id": null,
          "info": {
            "motion_control_result": [
              { "result": true, "pattern": "right" },
              { "result": true, "pattern": "left" },
              { "result": true, "pattern": "left" }
            ]
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:10.960546Z",
          "last_modified": "2026-07-06T12:38:10.960546Z"
        },
        {
          "id": "ac16bccc-478e-48ec-80e6-7cd0666a5e83",
          "files": [
            {
              "s3_link": "lr.ref-images:reference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg",
              "raw_data_in_base64": null
            }
          ],
          "type": 3,
          "parent_id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
          "info": {
            "angles": [0, -2],
            "image_info": {
              "quality": { "value": true, "failed_checks": null },
              "deepfake": { "confidence": 0.00021070241928100586 },
              "liveness": {
                "value": "real",
                "confidence": 0.9773591756820679,
                "attack_type": "none",
                "attack_type_scores": {
                  "none": 0.9773591756820679,
                  "photo": 0.0008513810934558892,
                  "replay": 0.007360487079161384,
                  "2d_mask": 0.0008028665221645174,
                  "3d_mask": 0.0017056756156491595,
                  "regions": 0.011920414007501181
                }
              }
            },
            "frame_number": 128
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:10.960546Z",
          "last_modified": "2026-07-06T12:38:10.960546Z"
        },
        {
          "id": "ce79a10b-26c1-4ccb-9c21-6f5439569a77",
          "files": [],
          "type": 5,
          "parent_id": null,
          "info": {
            "verification_info": {
              "fa_r": 0,
              "fr_r": 0.6750852465629578,
              "score": 0.9856855273246765,
              "distance": 2339
            }
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:12.671648Z",
          "last_modified": "2026-07-06T12:38:12.671648Z"
        }
      ],
      "creation_date": "2026-07-06T12:37:58.219058Z",
      "last_modified": "2026-07-06T12:37:58.219058Z"
    }

## Request for Retrieving Content by S3 Link​

This request returns binary content by an S3 link. The S3 link can be obtained from the attempt.

Request schema:
`GET /lrs/get_content/{content_link}`

### Request Headers​

Header | Description
--- | ---
`token` | Token of the `video-recorder` service. Stored in the `video-recorder-token` secret in the `./cfg/video-recorder.secrets.json` file.

### Example Request​

    curl -X 'GET' \
      'http://192.168.10.1/lrs/get_content/lr.ref-images%3Areference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg' \
      -H 'accept: application/json' \
      -H 'token: token'

# API Requests for Manual Photo Processing

This section describes requests that allow face detection on an image, building a biometric template, and comparing two such templates.

## Request for Face Detection on an Image​

This request performs face detection on the provided photo and returns its coordinates and key points.

Request schema:
`POST /face-detector-face-fitter/v2/process/image`

### Example Request​

    curl -X 'POST' \
      'http://192.168.10.1/face-detector-face-fitter/v2/process/image' \
      -H 'accept: application/json' \
      -H 'Content-Type: multipart/form-data' \
      -F 'image=@MinimumIMG.jpeg;type=image/jpeg'

### Request Body Parameters (multipart/form-data)​

Parameter | Description
--- | ---
`image` | Image to process. Supported formats: `jpeg`, `png`. Required.

### Example Response​

    {
      "_image": {
        "blob": "/9j/4A...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": { ... },
          "pose": {
            "yaw": -8.746259689331055,
            "roll": -0.09920386970043182,
            "pitch": 2.89003586769104
          },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [0.2, 0.21, 0.8466666666666667, 0.8433333333333334],
          "class": "face"
        }
      ]
    }

### Response Structure​

Field | Description
--- | ---
`_image` | Original image passed as input, in Base64 format.
`objects` | List of objects detected in the image with processing results. If empty, the detector did not find any face.
`objects[*].bbox` | Bounding box of the detected face, given in relative coordinates (normalised from 0 to 1) in order `[x1, y1, x2, y2]`. To convert to absolute pixel coordinates, multiply x‑coefficients by the original image width and y‑coefficients by its height.

## Request for Face Detection and Template Building​

This request detects a face in the provided photo and builds a biometric search template for it.

Request schema:
`POST /face-detector-template-extractor/v2/process/image`

### Example Request​

    curl -X 'POST' \
      'http://192.168.10.1/face-detector-template-extractor/v2/process/image' \
      -H 'accept: application/json' \
      -H 'Content-Type: multipart/form-data' \
      -F 'image=@MinimumIMG.jpeg;type=image/jpeg'

### Request Body Parameters (multipart/form-data)​

Parameter | Description
--- | ---
`image` | Image to process. Supported formats: `jpeg`, `png`. Required.

### Example Response​

    {
      "_image": {
        "blob": "/9j/4....",
        "format": "IMAGE"
      },
      "objects": [
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp2UD...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [0.2, 0.21, 0.8466666666666667, 0.8433333333333334],
          "class": "face",
          "keypoints": { ... },
          "pose": { ... }
        }
      ]
    }

### Response Structure​

Field | Description
--- | ---
`_image` | Original image passed as input, in Base64 format.
`objects` | List of objects detected in the image with processing results. If empty, the detector did not find any face.
`objects[*].template` | Biometric template information, including its binary data in Base64 format.

## Request for Liveness Estimation from an Image​

This request performs liveness detection for a previously detected face.

Request schema:
`POST /liveness-estimator/v2/process/sample`

### Example Request​

    curl -X 'POST' \
      'http://192.168.10.1/liveness-estimator/v2/process/sample' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{
      "objects": [ ... ]
    }'

### Request Body Parameters (application/json)​

The input is the result of a face detection or template building request. The request body must contain:

Field | Description
--- | ---
`_image` | Original image in Base64 format, passed to the previous handler.
`objects` | List of detected objects (must contain at least one face). If empty, the algorithm cannot perform liveness estimation.

#### Example Request Body​

    {
      "_image": {
        "blob": "/9j/4AAQSkZJRg...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": { ... },
          "pose": { ... },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [ ... ],
          "class": "face"
        }
      ]
    }

### Example Response​

    {
      "_image": {
        "blob": "/9j/4AAQSkZJ...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": { ... },
          "pose": { ... },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [ ... ],
          "class": "face",
          "liveness": {
            "confidence": 0.9966132640838623,
            "value": "real",
            "attack_type": "none",
            "attack_type_scores": {
              "none": 0.9966132640838623,
              "replay": 0.000978723779512078,
              "photo": 0.0021829818897145916,
              "regions": 9.736091756044222e-05,
              "2d_mask": 9.789085341223873e-05,
              "3d_mask": 2.977847593834453e-05
            }
          }
        }
      ]
    }

### Response Structure​

The response returns the same `_image` object and an extended `objects` list. For each detected face, a `liveness` block is added:

Field | Description
--- | ---
`objects[*].liveness.value` | Liveness algorithm verdict: `"real"` – live person.
`objects[*].liveness.confidence` | Algorithm confidence that the image shows a live person. Higher is better.
`objects[*].liveness.attack_type` | Recognised attack type (`"none"` means no attack).
`objects[*].liveness.attack_type_scores` | Algorithm confidence for each attack type.

## Request for Template Comparison​

This request compares two biometric templates obtained from the Template Building Request.

Request schema:
`POST /verify-matcher/v2/process/sample`

### Example Request​

    curl -X 'POST' \
      'http://192.168.10.1/verify-matcher/v2/process/sample' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{
      "objects": [ ... ]
    }'

### Request Body Parameters (application/json)​

The input is a list of two templates to compare. Order does not matter.

The request body contains the `objects` array – a list of objects with templates. Each object must contain:

Field | Description
--- | ---
`template` | Biometric template. Must be copied entirely from the `template` field of the template building API response.
`class` | Object type. Always must be `"face"`.

#### Example Request Body​

    {
      "objects": [
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "class": "face"
        },
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "class": "face"
        }
      ]
    }

### Example Response​

    {
      "objects": [ ... ],
      "verification": {
        "distance": 0,
        "fa_r": 0,
        "fr_r": 0.9825811982154846,
        "score": 0.9773591756820679
      }
    }

### Response Structure​

Field | Description
--- | ---
`objects` | List of objects passed in the request (returned unchanged).
`verification` | Result of comparing the two templates.
`verification.score` | Algorithm confidence that the faces belong to the same person. Higher means higher probability of a match.

# Attempt Object Structure

## Attempt Object Fields​

Field | Description
--- | ---
`id` | Unique attempt identifier.
`external_link` | External link associated with the attempt.
`content` | List of content items (processed binary data). Each item contains links to binary data and processing results.
`creation_date` | Attempt creation date and time.
`last_modified` | Last modification date and time.

## Content Item Fields​

Field | Description
--- | ---
`id` | Unique content item identifier.
`files` | List of S3 links to files. Contains links to video or images depending on the content type. Verification frames are not stored.
`type` | Content type: `1` – motion control video, `3` – reference frame, `5` – verification frame.
`info` | Biometric processing results. Format depends on the content type.
`exception_info` | Information about errors that occurred during content processing.

### Content Type 1 – Motion Control Video​

The `info` field contains motion analysis results as a list of actions and their verdicts.

    {
      "info": {
        "motion_control_result": [
          {
            "result": true,
            "pattern": "right"
          },
          {
            "result": true,
            "pattern": "left"
          },
          {
            "result": true,
            "pattern": "left"
          }
        ]
      }
    }

Field | Description
--- | ---
`result` | Action execution verdict (`true` – performed, `false` – not performed).
`pattern` | Action name. Possible values: `up`, `left`, `right`, `closer`, `farther`.

### Content Type 3 – Reference Frame​

The `info` field contains results of biometric processing of the reference frame.

    "info": {
      "angles": [0, -2],
      "image_info": {
        "quality": { "value": true, "failed_checks": null },
        "deepfake": { "confidence": 0.00021070241928100586 },
        "liveness": {
          "value": "real",
          "confidence": 0.9773591756820679,
          "attack_type": "none",
          "attack_type_scores": { ... }
        }
      },
      "frame_number": 128
    }

Field | Description
--- | ---
`quality.value` | Quality assessment verdict (`true` – quality acceptable).
`quality.failed_checks` | List of failed quality checks (if any).
`deepfake.confidence` | Algorithm confidence in the presence of deepfake signs. Lower is better.
`liveness.value` | Liveness verdict: `"real"` – live person.
`liveness.confidence` | Algorithm confidence that the image shows a live person. Higher is better.
`liveness.attack_type` | Recognised attack type (`"none"` – no attack).
`liveness.attack_type_scores` | Algorithm confidence for each attack type.

### Content Type 5 – Verification Frame​

The `info` field contains the result of comparing the reference frame with the frame from the web component.

    {
      "info": {
        "verification_info": {
          "fa_r": 0,
          "fr_r": 0.6750852465629578,
          "score": 0.9856855273246765,
          "distance": 2339
        }
      }
    }

Field | Description
--- | ---
`score` | Algorithm confidence in face match. Higher means higher probability that the faces belong to the same person.