openapi: 3.0.0
info:
  version: 'v.2.6.11'
  title: 'Luna events API'
  description: |
    VisionLabs Luna Events API.

    Intoduction

    This service is intended for searching events according to the specified filters and getting some statistics parameters of events. You can receive the following parameters:

    1) event count,
    2) average, max, min value numeric parameters.

    Events can be grouped by the creation time. Grouping is possible in two ways: grouping by time intervals and the frequency grouping (by day of month).

    The service store some fields in compressed state for query optimization and database size decrease.

      Mapping ethnicities to ID:

      | Group name | Group ID |
      | ---------- | -------- |
      | african_american  | 1 |
      | indian            | 2 |
      | asian             | 3 |
      | caucasian         | 4 |

      Mapping emotions to ID:

      | Group name | Group ID |
      | ---------- | -------- |
      | anger             | 1 |
      | disgust           | 2 |
      | fear              | 3 |
      | happiness         | 4 |
      | neutral           | 5 |
      | sadness           | 6 |
      | surprise          | 7 |

      Mapping masks to ID:

      | Group name | Group ID |
      | ---------- | -------- |
      | missing           | 1 |
      | medical_mask      | 2 |
      | occluded          | 3 |

      Mapping liveness to ID:

      | liveness | value |
      |--------------|---|
      | spoof        | 0 |
      | real         | 1 |
      | unknown      | 2 |


    OpenAPI specification is the only valid document providing up-to-date information about the service API.

    The specification can be used:

    - By documentation generation tools to visualize the API.
    - By code generation tools.

    All the documents and code generated using this specification can include inaccuracies and should be carefully checked.

    OpenAPI specification can be received using the "/docs/spec" resource. The "Accept" header should be set to "application/x-yaml".

components:
  headers:
    application_json:
      schema:
        type: string
        enum:
        - application/json
      required: true
      description: content type is application/json

    application_json_or_xbinary:
      schema:
        type: string
        enum:
          - application/json
          - application/x-sdk-descriptor
      required: true
      description: content type is application/json or application/x-sdk-descriptor

    text_plain:
      schema:
        type: string
        enum:
        - text/plain
      required: true
      description: content type is text/plain

    image_jpeg:
      schema:
        type: string
        enum:
        - image/jpeg
      description: content type is image/jpeg
      required: true

    luna_request_id:
      schema:
        type: string
        format: timestamp,uuid
        example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
        pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      description: request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
      required: true

    application_zip:
      schema:
        type: string
        enum:
        - application/zip
      required: true
      description: content type is application/zip

    content_disposition:
      schema:
        type: string
      example: 'attachment; filename=task_146.zip'
      required: true
      description: content disposition with filename

    docs_content_type:
      schema:
        type: string
        enum:
          - application/x-yaml
          - text/html
      required: true
      description: Type of receiving data

    text_html:
      schema:
        type: string
        enum:
          - text/html
      required: true
      description: Content type is text/html

    config_accept_content_type:
      schema:
        type: string
        enum:
          - application/json
          - text/plain
      required: false
      description: The content type of the response body.
  parameters:
    page:
      in: query
      name: page
      schema:
        type: integer
        minimum: 1
        default: 1
      description: a page number.

    accept:
      in: header
      schema:
        type: string
        example: "application/x-sdk-descriptor"
      description: content type which is acceptable for the response. If 'application/x-sdk-descriptor' is specified, the binary descriptor will be returned in the response body, otherwise 'application/json' content type will be applied.
      required: false
      name: Accept

    luna_request_id:
      in: header
      schema:
        type: string
        format: timestamp,uuid
        example: "1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a"
        pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      description: |
        external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
        If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.
      name: Luna-Request-Id

    wait_events_saving:
      in: query
      name: wait_events_saving
      schema:
        $ref: '#/components/schemas/int01'
      description: |
        whether to wait for events saving.

        If "0" is specified, the 202 status code will be expected in response to a successful request. This status code is returned after events are validated and added to the buffer. The system does not wait until the events are saved to the database. The events will be stored in the database after the response is sent.

        If "1" is specified, the 204 status code will be expected in response to a successful request. This status code is returned only after events are stored in the database.

    page_size:
      in: query
      name: page_size
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 10
      description: the number of items on page.

    limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 1000000
        default: 5
      description: the event limit in a match response

    threshold:
      in: query
      name: threshold
      schema:
        type: number
        minimum: 0.0
        maximum: 1.0
        default: 0.0
      description: the event similarity threshold in a match response - events with a similarity lower than this parameter will not be returned

    search_order:
      in: query
      name: order
      schema:
        type: string
        enum: ["asc", "desc"]
      description: |
        the sort order.

        By default, the results will be sorted by event creation time.
        If "desc" is set, the newest events will be shown first. If "asc" is set, the oldest events will be shown first.

        But if some event ID range filtres specified (`event_id__gte` or `event_id__lt`), the results will be sorted by event ID.

    match_order:
      in: query
      name: order
      schema:
        type: string
        enum: [ "asc", "desc" ]
      description: |
        the sort order.
        If "desc" is set, the most similar events will be shown first. If "asc" is set, the least similar events will be shown first.

    gender:
      in: query
      name: gender
      schema:
        type: integer
        enum: [0, 1]
      description: Gender. 1 - male, 0 - female.
      example: 1

    emotions:
      in: query
      name: emotions
      schema:
        type: string
        format: list of integer (1, 2, 3, 4, 5, 6, 7)
      description: |
        comma-separated list of predominant emotions. Each event from result will contain one of the given emotions.

        | emotions    | value |
        |-----------------|---|
        | anger           | 1 |
        | disgust         | 2 |
        | fear            | 3 |
        | happiness       | 4 |
        | neutral         | 5 |
        | sadness         | 6 |
        | surprise        | 7 |
      example: "1,2,3"

    masks:
      in: query
      name: masks
      schema:
        type: string
        format: list of integer (1, 2, 3)
      description: |
        comma-separated list of predominant masks. Each event from result will contain one of the given mask state.

        | mask        | value |
        |-----------------|---|
        | missing         | 1 |
        | medical_mask    | 2 |
        | occluded        | 3 |
      example: "1,2,3"

    ethnic_groups:
      in: query
      name: ethnic_groups
      schema:
        type: string
        format: list of integer (1, 2, 3, 4)
      description: |
        comma-separated list of dominant ethnic group. Each event from result will contain one of the given ethnic groups.

        | ethnicity    | value |
        |------------------|---|
        | African american | 1 |
        | Indian           | 2 |
        | Asian            | 3 |
        | Caucasian        | 4 |

      example: "1,2"

    liveness:
      in: query
      name: liveness
      schema:
        type: string
        format: list of integer (0, 1 ,2)
      description: |
        comma-separated list of dominant liveness. Each event from result will contain one of the given liveness.

        | liveness | value |
        |--------------|---|
        | spoof        | 0 |
        | real         | 1 |
        | unknown      | 2 |

      example: "1,2"

    tags:
      in: query
      name: tags
      schema:
        type: array
        items:
          $ref: '#/components/schemas/tag'
        minItems: 0
      explode: false
      description: A comma-separated list of tags. Each event from result will contain all of the given tags.
      example:
        - tag_1
        - tag_2

    age__lt:
      in: query
      name: age__lt
      schema:
        type: integer
        minimum: 0
        maximum: 100
      description: age upper excluded bound.
      example: 50

    age__gte:
      in: query
      name: age__gte
      schema:
        type: integer
        minimum: 0
        maximum: 100
      description: age lower included bound.
      example: 50

    account_id:
      in: query
      name: account_id
      schema:
        $ref: '#/components/schemas/uuid'
      description: account id
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb'

    face_ids:
      in: query
      name: face_ids
      schema:
        type: string
        format: list of uuid
      description: list of comma-separated face ids.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38'

    event_ids:
      in: query
      name: event_ids
      schema:
        type: string
        format: list of uuid.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38'
      description: a list of comma-separated event ids.

    event_id__gte:
      in: query
      name: event_id__gte
      schema:
        type: string
        format: uuid.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb'
      description: lower including event id boundary.

    event_id__lt:
      in: query
      name: event_id__lt
      schema:
        type: string
        format: uuid.
      example: '346a5645-ec89-4806-820a-dbcb6e0dc38'
      description: upper excluding event id boundary.

    handler_id:
      in: query
      name: handler_id
      schema:
        type: string
        format: uuid.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb'
      description: handler id.

    handler_ids:
      in: query
      name: handler_ids
      schema:
        type: string
        format: list of uuid.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38'
      description: a list of comma-separated handler ids.

    external_id:
      in: query
      name: external_id
      schema:
        type: string
        maxLength: 36
      description: external id.

    external_ids:
      in: query
      name: external_ids
      schema:
        type: string
        format: list of strings.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38'
      description: a list of comma-separated external ids.

    user_data:
      in: query
      name: user_data
      schema:
        type: string
      description: find all objects with user_data that is similar to this parameter.
      example: "user_data"

    sources:
      in: query
      name: sources
      schema:
        type: string
      description: Comma-separated list of sources. Each event from result will contain one of the given sources.
      example: "cam1,cam2"

    cities:
      in: query
      name: cities
      schema:
        type: string
      description: Comma-separated list of cities. Each event from result will contain one of the given cities in location.
      example: "moscow,New-York"

    areas:
      in: query
      name: areas
      schema:
        type: string
      description: Comma-separated list of areas. Each event from result will contain one of the given areas in location.
      example: "CAO,central park"

    districts:
      in: query
      name: districts
      schema:
        type: string
      description: Comma-separated list of districts. Each event from result will contain one of the given districts in location.
      example: "mitino,central park"

    streets:
      in: query
      name: streets
      schema:
        type: string
      description: |
        Comma-separated list of streets. Each event from result will contain one of the given streets  in location.
      example: "arbat,schepkina"

    house_numbers:
      in: query
      name: house_numbers
      schema:
        type: string
      description: |
        Comma-separated list of house numbers. Each event from result will contain one of the given house numbers
        in location.
      example: "1,1/2str3"

    origin_longitude:
      in: query
      name: origin_longitude
      schema:
        $ref: '#/components/schemas/longitude'
      description: |
        longitude origin in degrees, a part of composite geo position filter.
                Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.
                Geo position filter is considered as properly specified if both *origin_longitude* and
                *origin_latitude* are set, and considered as properly empty if neither of *origin_longitude*,
                *origin_latitude*, *longitude_delta*, *latitude_delta* is set.
      example: "36.616"

    origin_latitude:
      in: query
      name: origin_latitude
      schema:
        $ref: '#/components/schemas/latitude'
      description: |
        latitude origin in degrees, a part of composite geo position filter.
                Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.
                Geo position filter is considered as properly specified if both *origin_longitude* and
                *origin_latitude* are set, and considered as properly empty if neither of *origin_longitude*,
                *origin_latitude*, *longitude_delta*, *latitude_delta* is set.
      example: "55.752"

    longitude_delta:
      in: query
      name: longitude_delta
      schema:
        type: number
        minimum: 0
        maximum: 90
        default: 0.01
      description: |
        longitude delta in degrees, a part of composite geo position filter.
                Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.
                Geo position filter is considered as properly specified if both *origin_longitude* and
                *origin_latitude* are set, and considered as properly empty if neither of *origin_longitude*,
                *origin_latitude*, *longitude_delta*, *latitude_delta* is set. If both *origin_longitude* and
                *origin_latitude* are set and *longitude_delta* is not set - default is applied.
                WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole
                are not fully supported due to features of database spatial index - filter result may be unexpected.
                Box edges more than 180 degrees long are not allowed. Boundaries of valid range are **exclusive**.
                NOTE: highly recommended for citywide use only.
      example: "0.01"

    latitude_delta:
      in: query
      name: latitude_delta
      schema:
        type: number
        minimum: 0
        maximum: 90
        default: 0.01
      description: |
        latitude delta in degrees, a part of composite geo position filter.
                Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.
                Geo position filter is considered as properly specified if both *origin_longitude* and
                *origin_latitude* are set, and considered as properly empty if neither of *origin_longitude*,
                *origin_latitude*, *longitude_delta*, *latitude_delta* is set. If both *origin_longitude* and
                *origin_latitude* are set and *latitude_delta* is not set - default is applied.
                WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole
                are not fully supported due to features of database spatial index - filter result may be unexpected.
                Box edges more than 180 degrees long are not allowed. Boundaries of valid range are **exclusive**.
                NOTE: highly recommended for citywide use only.
      example: "0.01"

    top_matching_candidates_label:
      in: query
      name: top_matching_candidates_label
      schema:
        type: string
      description: Top matching candidates label. Each event from result will contain the given label.
      example: "matching_label"

    top_similar_object_ids:
      in: query
      name: top_similar_object_ids
      schema:
        type: array
        items:
          $ref: '#/components/schemas/uuid'
      description: Comma-separated list of top similar object ids. Each event from result will contain one of the given top similar object ids.

    top_similar_external_ids:
      in: query
      name: top_similar_external_ids
      schema:
        type: array
        items:
          $ref: '#/components/schemas/external_id'
      description: Comma-separated list of top similar external ids. Each event from result will contain one of the given top similar external ids.

    top_similar_object_similarity__gte:
      in: query
      name: top_similar_object_similarity__gte
      schema:
        type: number
      description: Top similar object similarity lower included bound.
      example: 0.5

    top_similar_object_similarity__lt:
      in: query
      name: top_similar_object_similarity__lt
      schema:
        type: number
      description: Top similar object similarity upper excluded bound.
      example: 0.5

    get_event_target:
      in: query
      name: target
      schema:
        type: string
        enum: ["account_id", "create_time", "end_time", "event_id", "handler_id", "external_id", "source", "top_match",
               "match_result", "face_detections", "face_id", "attach_result", "gender", "age", "emotion",
               "ethnic_group", "liveness", "body_detections", "tags", "user_data", "location", "mask", "track_id"]
      description: |
        Comma-separated list of event fields.
        If set, each event from result will contain only specified fields, otherwise, events with all fields will be returned.
      example: "extract_result"

    post_event_match_target:
      in: query
      name: target
      schema:
        type: string
        enum: ["account_id", "create_time", "end_time", "event_id", "handler_id", "external_id", "source", "top_match",
               "match_result", "extract_result", "face_id", "attach_result", "gender", "age", "emotion", "ethnic_group",
               "liveness", "tags", "user_data", "location", "similarity", "mask", "track_id"]
      description: |
        Comma-separated list of event fields.
        If set, each event from result will contain only specified fields, otherwise, events with the "event_id" and "similarity" fields will be returned.
      example: "extract_result,similarity"

    list_id:
      in: query
      name: list_id
      schema:
        $ref: '#/components/schemas/uuid'
      description: id of a list that contains faces.

    applicationJsonContent:
      in: header
      name: Content-Type
      schema:
        type: string
        enum:
        - application/json
      description: content type is application/json.

    insert_time__lt:
      in: query
      name: insert_time__lt
      schema:
        type: string
        format: date-time
      description: The upper insert time excluding boundary.
      example: "2018-08-11T09:11:41.674Z"

    insert_time__gte:
      in: query
      name: insert_time__gte
      schema:
        type: string
        format: date-time
      description: The lower insert time including boundary.
      example: "2018-08-11T09:11:41.674Z"

    create_time__lt:
      in: query
      name: create_time__lt
      schema:
        type: string
        format: date-time
      description: upper bound for object create_time.
      example: "2018-08-11T09:11:41.674Z"

    create_time__gte:
      in: query
      name: create_time__gte
      schema:
        type: string
        format: date-time
      description: The lower create time including boundary.
      example: "2018-08-11T09:11:41.674Z"

    end_time__lt:
      in: query
      name: end_time__lt
      schema:
        type: string
        format: date-time
      description: upper bound for object end_time.
      example: "2018-08-11T09:11:41.674Z"

    end_time__gte:
      in: query
      name: end_time__gte
      schema:
        type: string
        format: date-time
      description: The lower end time including boundary.
      example: "2018-08-11T09:11:41.674Z"

    accept_docs_handler:
      in: header
      name: Accept
      schema:
        $ref: '#/components/schemas/accept_docs_handler'
      required: true
      description: acceptable type of receiving data

    descriptor_version:
      in: query
      name: descriptor_version
      schema:
        type: integer
        minimum: 0
        maximum: 110
        # Fake boundaries, used to prevent schematesis from sending huge integers.
      description: event descriptor version. By default used the platform default descriptor version.
      example: 56

    descriptor_version_required:
      in: query
      name: version
      schema:
        type: integer
        minimum: 0
        maximum: 1000
        # Fake boundaries, used to prevent schematesis from sending huge integers.
      description: event descriptor version.
      required: true
      example: 56

    event_id:
      in: path
      name: event_id
      schema:
        $ref: '#/components/schemas/uuid'
      required: true
      description: event id

    descriptor_type:
      in: query
      name: descriptor_type
      schema:
        type: string
        enum: [face, body]
      description: The type of the event's descriptor.
      example: face

    descriptor_type_required:
      in: query
      name: descriptor_type
      schema:
        type: string
        enum: [face, body]
      description: The type of the event's descriptor.
      required: true
      example: face

    track_ids:
      in: query
      name: track_ids
      schema:
        type: string
        format: list of track ids
      example: 'track_id1,track_id_2'
      description: a list of comma-separated track ids.

    kind:
      in: query
      name: kind
      schema:
        type: string
        enum: [basic_attributes, face_descriptor, body_descriptor]
      description: |
          kind of missing attributes to look for.

          Only 1 value at time is supported because the response doesn't
          contain information required to distinguish kinds of the events.
      required: true
      example: basic_attributes

    missing_version:
      in: query
      name: missing_version
      schema:
        type: integer
      description: event descriptor version. By default used the platform default descriptor version.
      example: 56

    application_json_or_msgpack_content:
      in: header
      name: Content-Type
      schema:
        type: string
        enum:
          - application/json
          - application/msgpack
      description: The response content type header.

    accept_config_handler:
      in: header
      name: Accept
      schema:
        type: string
        enum:
          - application/json
          - text/plain
        description: One of application/json, text/plain
      required: false
      description: acceptable type of receiving data

    delete_event_target:
      in: query
      name: target
      schema:
        type: array
        items:
          type: string
          enum: [ face_samples, body_samples, image_origins ]
        default: [ face_samples, body_samples, image_origins ]
      explode: false
      description: |
        Comma-separated list of event deletion info attributes.
        If set, each item from the result will contain only specified attributes in addition to the event ID, otherwise, all the deletion info attributes will be returned.
        If empty value set, each item from the result will contain only event ID.
      example: image_origins
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: integer
          description: error code.
        desc:
          type: string
          description: short error description.
        detail:
          type: string
          description: error details.
      required:
      - error_code
      - detail
      - desc
      example:
        error_code: 1
        detail: "internal server error"
        desc: "internal server error"

    uuid:
      type: string
      format: uuid
      pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'
      example: "557d54ec-29ad-4f3c-93b4-c9092ef12515"

    account_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: account id.
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    sample_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: sample id.
      nullable: true
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    external_id:
      description: user-defined external id for face
      type: string
      pattern: "^[^\\x00]*$"
      example: "external id"
      maxLength: 36

    track_id:
      description: event track id
      type: string
      pattern: '^[a-zA-Z0-9_\-]{1,36}$'
      example: "useful_track_id_number_1"

    face_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: face id.
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    list_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: list id.
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    event_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: event id.
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    handler_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: handler id.
      example: "b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    count:
      type: integer
      minimum: 0
      description: object count.
      example: 100

    int01:
      type: integer
      default: 0
      enum:
      - 0
      - 1

    int0100:
      type: integer
      minimum: 0
      maximum: 100

    int0180:
      type: integer
      default: 180
      minimum: 0
      maximum: 180

    number01:
      type: number
      minimum: 0
      maximum: 1

    estimation_not_nullable:
      type: number
      format: double
      maximum: 1
      minimum: 0
      nullable: false

    time:
      type: string
      format: date-time
      example: "2018-08-11T09:11:41.674Z"
      description: time in format RFC 3339

    detect_time:
      allOf:
        - $ref: "#/components/schemas/time"
        - description: detection time
      example: "2018-08-11T09:11:41.674Z"

    image_origin:
      type: string
      maxLength: 256
      description: the image url - source of the detection
      nullable: true
      example: "/6/images/b668c4a5-2191-476e-a261-3b4f9ce2e25e"

    column:
      type: string
      enum: [event_id, external_id, handler_id, source, top_similar_object_id, top_similar_external_id, create_time,
             end_time, liveness, top_matching_candidates_label, top_similar_object_similarity, face_id, gender, age,
             emotion, ethnic_group, user_data, tags, city, area, district, street, house_number, geo_position, mask,
             track_id]
      description: fields to aggregate.
      example: "source"

    gender:
      allOf:
        - $ref: '#/components/schemas/int01'
        - description: gender, 0 - female, 1 - male

    age:
      allOf:
        - $ref: '#/components/schemas/int0100'
        - description: Age

    aggregator:
      type: string
      enum: [count, max, min, avg, group_by]
      example: "count"
      description: aggregation function for column.
      default: count

    operator_filter:
      type: string
      enum: [eq, neq, in, nin, like, nlike, gt, gte, lt, lte, covered]
      description: |
        filter operator. For tags it is required to be like/nlike only.
        For geo position filter it is required to be covered only.
      example: "gt"

    operator_period:
      type: string
      enum: [gt, gte, lt, lte]
      description: filter operator for event creation time.
      example: "gt"

    value_period:
      type: string
      format: date-time
      example: "2018-01-01T00:00:00Z"
      pattern: (^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$|^now-\d+(y|M|w|d|h|m|s)$)
      description: filter value for event creation time. In ISO or now-time format.

    longitude:
      type: number
      minimum: -180
      maximum: 180
      example: 36.616

    latitude:
      type: number
      minimum: -90
      maximum: 90
      example: 55.752

    geo_position:
      type: object
      description: geo position specified by geographic coordinates - longitude and latitude.
      properties:
        longitude:
          allOf:
            - $ref: '#/components/schemas/longitude'
            - description: longitude in degrees
        latitude:
          allOf:
            - $ref: '#/components/schemas/latitude'
            - description: latitude in degrees
      required: [longitude, latitude]

    geo_position_bbox:
      description: |
          geo position filter is a bounding box specified by coordinates of its center (origin) and some delta.
          WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are
          not fully supported due to features of database spatial index - filter result may be unexpected.
      properties:
        origin_longitude:
          allOf:
            - $ref: '#/components/schemas/longitude'
            - description: origin longitude in degrees
        origin_latitude:
          allOf:
            - $ref: '#/components/schemas/latitude'
            - description: origin latitude in degrees
        longitude_delta:
          description: |
              longitude delta in degrees. Box edges more than 180 degrees long are not allowed.
              Boundaries of valid range are **exclusive**. NOTE: highly recommended for citywide use only.
          type: number
          minimum: 0
          maximum: 90
          default: 0.01
          example: 0.01
        latitude_delta:
          description: |
              latitude delta in degrees. Box edges more than 180 degrees long are not allowed.
              Boundaries of valid range are **exclusive**. NOTE: highly recommended for citywide use only.
          type: number
          minimum: 0
          maximum: 90
          default: 0.01
          example: 0.01
      required: [origin_longitude, origin_latitude]

    value_filter:
      oneOf:
        - type: string
        - type: number
        - type: array
          items:
            oneOf:
              - type: string
              - type: number
        - $ref: '#/components/schemas/geo_position_bbox'
      description: |
        filter value. It is required to be string, integer, float or its array
        or object with specific properties in case of geo position filter -
        geo position filter is bounding box specified by coordinates of its center (origin) and some delta.
      example: "London"

    user_data:
      description: user data.
      type: string
      pattern: "^[^\\x00]*$"
      maxLength: 128
      default: ""

    face_user_data:
      allOf:
        - $ref: '#/components/schemas/user_data'
      description: user data associated with face
      example: "face of person"

    location_str:
      type: string
      pattern: "^[^\\x00]*$"
      maxLength: 36
      nullable: true

    location:
      type: object
      description: information about a place where event is incidented
      properties:
        city:
          allOf:
            - $ref: '#/components/schemas/location_str'
            - description: city where event is incidented
        area:
          allOf:
            - $ref: '#/components/schemas/location_str'
            - description: area where event is incidented
        district:
          allOf:
            - $ref: '#/components/schemas/location_str'
            - description: district where event is incidented
        street:
          allOf:
            - $ref: '#/components/schemas/location_str'
            - description: street where event is incidented
        house_number:
          allOf:
            - $ref: '#/components/schemas/location_str'
            - description: house number where event is incidented
        geo_position:
          allOf:
            - $ref: '#/components/schemas/geo_position'
            - nullable: true
      required: [city, area, district, street, house_number, geo_position]

      example:
        city: "Moscow"
        area: "CAO"
        district: "Arbat"
        street: "Arbat"
        house_number: "3"
        geo_position:
          longitude: 36.616
          latitude: 55.752

    target:
      type: object
      properties:
        column:
          $ref: '#/components/schemas/column'
        aggregator:
          $ref: '#/components/schemas/aggregator'
      required: [column , aggregator]

    targets:
      type: array
      description: |
        Fields and functions to aggregate.

        Allowed usage of aggregators is:

        | Column                        | Aggregator |     |     |     |          |
        |-------------------------------|------------|-----|-----|-----|----------|
        |                               | count      | max | min | avg | group_by |
        | event_id                      | +          | -   | -   | -   | +        |
        | external_id                   | +          | -   | -   | -   | +        |
        | handler_id                    | +          | -   | -   | -   | +        |
        | source                        | +          | -   | -   | -   | +        |
        | top_similar_object_id         | +          | -   | -   | -   | +        |
        | top_similar_external_id       | +          | -   | -   | -   | +        |
        | top_matching_candidates_label | +          | -   | -   | -   | +        |
        | create_time                   | +          | +   | +   | -   | -        |
        | end_time                      | +          | +   | +   | -   | -        |
        | top_similar_object_similarity | +          | +   | +   | +   | -        |
        | face_id                       | +          | -   | -   | -   | +        |
        | gender                        | +          | +   | +   | +   | +        |
        | age                           | +          | +   | +   | +   | +        |
        | emotion                       | +          | +   | +   | +   | +        |
        | mask                          | +          | +   | +   | +   | +        |
        | ethnic_group                  | +          | +   | +   | +   | +        |
        | liveness                      | +          | +   | +   | +   | +        |
        | user_data                     | +          | -   | -   | -   | +        |
        | tags                          | +          | +   | +   | -   | -        |
        | city                          | +          | -   | -   | -   | +        |
        | area                          | +          | -   | -   | -   | +        |
        | district                      | +          | -   | -   | -   | +        |
        | street                        | +          | -   | -   | -   | +        |
        | house_number                  | +          | -   | -   | -   | +        |
        | geo_position                  | +          | -   | -   | -   | -        |
        | track_id                      | +          | -   | -   | -   | +        |

      items:
        $ref: '#/components/schemas/target'
      minItems: 1
      default:
        - {'column': 'event_id', 'aggregator': 'count'}

    filter:
      type: object
      description: filter for sample restriction.
      properties:
        column:
          $ref: '#/components/schemas/column'
        operator:
          $ref: '#/components/schemas/operator_filter'
        value:
          $ref: '#/components/schemas/value_filter'
      required: [column , operator, value]

    filters:
      type: array
      description: |
        Set of filters for sample restriction.

        Allowed usage of filters is:

        | Filter                        | Operator    |         |         |                  |         |
        |-------------------------------|-------------|---------|---------|------------------|---------|
        |                               | like, nlike | in, nin | eq, neq | gt, gte, lt, lte | covered |
        | tags                          | +           | -       | -       | -                | -       |
        | source                        | -           | +       | +       | -                | -       |
        | user_data                     | -           | +       | +       | -                | -       |
        | account_id                    | -           | +       | +       | +                | -       |
        | event_id                      | -           | +       | +       | +                | -       |
        | external_id                   | -           | +       | +       | +                | -       |
        | handler_id                    | -           | +       | +       | +                | -       |
        | top_similar_object_id         | -           | +       | +       | +                | -       |
        | top_similar_external_id       | -           | +       | +       | +                | -       |
        | top_matching_candidates_label | -           | +       | +       | -                | -       |
        | top_similar_object_similarity | -           | -       | -       | +                | -       |
        | face_id                       | -           | +       | +       | +                | -       |
        | gender                        | -           | +       | +       | +                | -       |
        | age                           | -           | +       | +       | +                | -       |
        | emotion                       | -           | +       | +       | +                | -       |
        | mask                          | -           | +       | +       | +                | -       |
        | ethnic_group                  | -           | +       | +       | +                | -       |
        | liveness                      | -           | +       | +       | +                | -       |
        | city                          | -           | +       | +       | -                | -       |
        | area                          | -           | +       | +       | -                | -       |
        | district                      | -           | +       | +       | -                | -       |
        | street                        | -           | +       | +       | -                | -       |
        | house_number                  | -           | +       | +       | -                | -       |
        | geo_position                  | -           | -       | -       | -                | +       |
        | track_id                      | -           | +       | +       | -                | -       |

        Warning: must be at least one aggregator different with 'group_by' in request

      items:
        $ref: '#/components/schemas/filter'
      minItems: 0

    period:
      description: min and max of event creation time for sample restriction.
      type: object
      properties:
        operator:
          $ref: '#/components/schemas/operator_period'
        value:
          $ref: '#/components/schemas/value_period'
      required: [operator, value]

    periods:
      type: array
      description: it is possible to set start and end of period.
      items:
        $ref: '#/components/schemas/period'
      minItems: 0

    group_by:
      type: string
      description: |
        event for grouping by creation time.

        Grouping is possible in two ways

        1) Grouping by time intervals - number and dimension

        | The parameter value | Description  |
        |---------------------|--------------|
        | `1m`                | one minute   |
        | `2h`                | two hours    |
        | `7d`                | seven days   |
        | `5w`                | five weeks   |
        | `3M`                | three months |
        | `10y`               | ten years    |

        2) The frequency grouping - one of the following

        | The parameter value | Description        |
        |---------------------|--------------------|
        | `monthOfYear`       | by month of year   |
        | `weekOfYear`        | by week of year    |
        | `dayOfYear`         | by day of year     |
        | `dayOfMonth`        | by day of month    |
        | `dayOfWeek`         | by day of week     |
        | `hourOfDay`         | by hours of day    |
        | `minuteOfHour`      | by minutes of hour |

      example: "dayOfWeek"

    ethnicities_enum:
      type: integer
      enum: [1, 2, 3, 4]
      description: |
        reference ethnicity

        | ethnicity    | value |
        |------------------|---|
        | African american | 1 |
        | Indian           | 2 |
        | Asian            | 3 |
        | Caucasian        | 4 |

    predominant_ethnicity:
      type: string
      description: most likely ethnicity of a human from the event
      enum: ["african_american", "indian", "caucasian", "asian"]

    emotion_enum:
      description: |
        predominant emotion.

        | emotions    | value |
        |-----------------|---|
        | anger           | 1 |
        | disgust         | 2 |
        | fear            | 3 |
        | happiness       | 4 |
        | neutral         | 5 |
        | sadness         | 6 |
        | surprise        | 7 |

      type: integer
      enum: [1, 2, 3, 4, 5, 6, 7]

    mask_enum:
      description: |
        predominant mask.

        | masks      | value |
        |----------------|---|
        | missing        | 1 |
        | medical_mask   | 2 |
        | occluded       | 3 |

      type: integer
      enum: [1, 2, 3]

    liveness_enum:
      description: |
        predominant liveness.

        | liveness | value |
        |--------------|---|
        | spoof        | 0 |
        | real         | 1 |
        | unknown      | 2 |

      type: integer
      enum: [0, 1, 2]

    int_version:
      type: integer
      minimum: 0

    version:
      type: object
      properties:
        Version:
          type: object
          properties:
            api:
              allOf:
                - $ref: '#/components/schemas/int_version'
                - description: an api version of service.
            major:
              allOf:
                - $ref: '#/components/schemas/int_version'
                - description: a major version of service.
            minor:
              allOf:
                - $ref: '#/components/schemas/int_version'
                - description: a minor version of service.
            patch:
              allOf:
                - $ref: '#/components/schemas/int_version'
                - description: a patch version of service.
          required: [api, major, minor, patch]
      required: [Version]

      example:
        Version:
          api: 1
          major: 0
          minor: 0
          patch: 0

    accept_docs_handler:
      type: string
      enum: [application/x-yaml, text/html]
      description: One of application/x-yaml, text/html

    avatar:
      type: string
      format: uri-reference
      default: ""
      nullable: true
      description: avatar for the face, references to a sample or a user-defined reference.

    lists:
      type: array
      items:
        $ref: '#/components/schemas/list_id'
      minItems: 0
      description: list of luna lists, which contain the face.

    url:
      type: string
      description: face url
      nullable: true

    face:
      type: object
      properties:
        face_id:
          $ref: '#/components/schemas/face_id'
        lists:
          type: array
          items:
            $ref: '#/components/schemas/list_id'
          minItems: 0
          description: list of luna lists, which contain the face.
      required: [face_id, lists]
      example:
        face_id: "426542d6-5509-4e5b-8a01-e2abd5c0a8c6"
        lists: ["429b0e78-4616-426a-b57f-02baa72d638d", "6d037c33-31ec-4d73-b3b3-ec80b09446c2"]

    face_candidate:
      type: object
      properties:
        face_id:
          $ref: '#/components/schemas/face_id'
        external_id:
          $ref: '#/components/schemas/external_id'
        user_data:
          $ref: '#/components/schemas/face_user_data'
        create_time:
          allOf:
            - $ref: "#/components/schemas/time"
            - description: time of the face creation.

    face_candidate_reply:
      type: object
      properties:
        face_id:
          allOf:
          - $ref: '#/components/schemas/face_id'
          nullable: true
        external_id:
          allOf:
          - $ref: '#/components/schemas/external_id'
          nullable: true
        user_data:
          allOf:
          - $ref: '#/components/schemas/face_user_data'
          nullable: true
        create_time:
          allOf:
          - $ref: "#/components/schemas/time"
          - description: time of the face creation.
          nullable: true
      required: [face_id, external_id, user_data, create_time]

    event_candidate:
      type: object
      properties:
        event_id:
          $ref: '#/components/schemas/event_id'
        external_id:
          $ref: '#/components/schemas/external_id'
        handler_id:
          $ref: '#/components/schemas/handler_id'
        source:
          allOf:
          - $ref: '#/components/schemas/source'
          nullable: true
        user_data:
          $ref: '#/components/schemas/face_user_data'
        create_time:
          allOf:
            - $ref: "#/components/schemas/time"
            - description: time of the event creation.

    event_candidate_reply:
      type: object
      properties:
        event_id:
          allOf:
          - $ref: '#/components/schemas/event_id'
          nullable: true
        external_id:
          allOf:
          - $ref: '#/components/schemas/external_id'
          nullable: true
        handler_id:
          allOf:
          - $ref: '#/components/schemas/handler_id'
          nullable: true
        source:
          allOf:
          - $ref: '#/components/schemas/source'
          nullable: true
        user_data:
          allOf:
          - $ref: '#/components/schemas/face_user_data'
          nullable: true
        create_time:
          allOf:
          - $ref: "#/components/schemas/time"
          - description: time of the event creation.
          nullable: true
      required: [event_id, external_id, handler_id, source, user_data, create_time]

    source:
      description: additional information that user provides with event.
      type: string
      pattern: "^[^\\x00]*$"
      example: "3rd Avenue"

    tag:
      description: tag. All characters allowed except *NUL*.
      type: string
      pattern: "^[^\\x00]+$"
      example: "good"
      maxLength: 36

    Tags:
      description: tag array.
      type: array
      items:
        $ref: '#/components/schemas/tag'
      example: ["tag1", "tag2"]

    top_matching_candidates_label:
      description: top matching candidates label
      type: string
      pattern: "^[^\\x00]*$"
      maxLength: 36
      example: "good guys"

    top_match_face:
      type: object
      description: the most similar object is face
      properties:
        face_id:
          allOf:
          - $ref: '#/components/schemas/face_id'
          nullable: true
        similarity:
          $ref: '#/components/schemas/face_similarity'
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
        external_id:
          allOf:
          - $ref: '#/components/schemas/external_id'
          nullable: true
      required: [face_id, similarity, label, external_id]

    top_match_event:
      type: object
      description: the most similar object is event
      properties:
        event_id:
          allOf:
          - $ref: '#/components/schemas/event_id'
          nullable: true
        similarity:
          $ref: '#/components/schemas/event_similarity'
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
        external_id:
          allOf:
          - $ref: '#/components/schemas/external_id'
          nullable: true
      required: [event_id, similarity, label, external_id]

    Event:
      type: object
      description: event.
      properties:
        create_time:
          allOf:
            - $ref: '#/components/schemas/time'
          description: event creation time
        end_time:
          allOf:
            - $ref: '#/components/schemas/time'
          description: event end time
        event_id:
          $ref: '#/components/schemas/event_id'
        handler_id:
          allOf:
            - $ref: '#/components/schemas/handler_id'
          description: id of the handler, which gave birth to the event.
        account_id:
          $ref: '#/components/schemas/account_id'
        external_id:
          $ref: '#/components/schemas/external_id'
        source:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/source'
        top_match:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/top_match_face'
            - $ref: '#/components/schemas/top_match_event'
        match_result:
          description: object that contains match result.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/match_candidates_reply'
          example:
            [{
               "label": "good guys",
               "candidates": [{
                              "face":{
                                "face_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c6",
                                "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
                                "user_data": "fox1991",
                                "create_time": "2018-08-11T09:11:41.674Z"
                              },
                              "similarity": 0.5
                            }]},
             {
               "label": "bad guys",
               "candidates": [{
                              "event":{
                                "event_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7",
                                "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
                                "user_data": "fox1991",
                                "create_time": "2018-08-11T09:11:41.674Z",
                                "handler_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7",
                                "source": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7"
                              },
                              "similarity": 0.3
                            }]}]
        face_detections:
          description: List of all face detection and corresponding sample ids
          type: array
          nullable: true
          items:
            type: object
            properties:
              sample_id:
                $ref: '#/components/schemas/sample_id'
              detection:
                type: object
                description: detection
                properties:
                  rect:
                    type: object
                    description: detection rectangle
                    properties:
                      x:
                        type: integer
                        description: detection rectangle x coordinate
                      y:
                        type: integer
                        description: detection rectangle y coordinate
                      width:
                        type: integer
                        description: detection rectangle width
                      height:
                        type: integer
                        description: detection rectangle height
                    required: [x, y, width, height]
                required: [rect]
              detect_time:
                $ref: '#/components/schemas/detect_time'
              image_origin:
                $ref: '#/components/schemas/image_origin'
            required: [sample_id, detect_time, image_origin]
        body_detections:
          description: List of all body detection and corresponding sample ids
          type: array
          nullable: true
          items:
            type: object
            properties:
              sample_id:
                $ref: '#/components/schemas/sample_id'
              detection:
                type: object
                description: detection
                properties:
                  rect:
                    type: object
                    description: detection rectangle
                    properties:
                      x:
                        type: integer
                        description: detection rectangle x coordinate
                      y:
                        type: integer
                        description: detection rectangle y coordinate
                      width:
                        type: integer
                        description: detection rectangle width
                      height:
                        type: integer
                        description: detection rectangle height
                    required: [x, y, width, height]
                required: [rect]
              detect_time:
                $ref: '#/components/schemas/detect_time'
              image_origin:
                $ref: '#/components/schemas/image_origin'
            required: [sample_id, detect_time, image_origin]
        face_id:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/face_id'
        attach_result:
          description: contains attached lists ids.
          type: array
          items:
            $ref: '#/components/schemas/list_id'
          minItems: 0
        gender:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/gender'
        age:
          description: Age.
          type: integer
          nullable: true
          maximum: 100
          minimum: 0
        emotion:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/emotion_enum'
        mask:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/mask_enum'
        ethnic_group:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/ethnicities_enum'
        liveness:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/liveness_enum'
        tags:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/Tags'
        user_data:
          $ref: '#/components/schemas/user_data'
        location:
          $ref: '#/components/schemas/location'
        track_id:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/track_id'

    Events:
      type: array
      items:
        $ref: '#/components/schemas/Event'

    EventsWithoutCount:
      type: object
      properties:
        events:
          $ref: '#/components/schemas/Events'

    face_similarity:
      allOf:
        - $ref: '#/components/schemas/number01'
      description: face similarity

    event_similarity:
      allOf:
        - $ref: '#/components/schemas/number01'
      description: event similarity

    face_match_candidate:
      type: object
      properties:
        face:
          $ref: '#/components/schemas/face_candidate'
        similarity:
          $ref: '#/components/schemas/face_similarity'
      required: [face, similarity]

    face_match_candidate_reply:
      type: object
      properties:
        face:
          $ref: '#/components/schemas/face_candidate_reply'
        similarity:
          $ref: '#/components/schemas/face_similarity'
      required: [face, similarity]

    event_match_candidate:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/event_candidate'
        similarity:
          $ref: '#/components/schemas/event_similarity'
      required: [event, similarity]

    event_match_candidate_reply:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/event_candidate_reply'
        similarity:
          $ref: '#/components/schemas/event_similarity'
      required: [event, similarity]

    match_candidates_faces:
      type: array
      description: list of faces candidates
      items:
        $ref: '#/components/schemas/face_match_candidate'

    match_candidates_faces_reply:
      type: object
      properties:
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
        candidates:
          type: array
          description: list of faces candidates
          items:
            $ref: '#/components/schemas/face_match_candidate_reply'
      required: [label, candidates]

    match_candidates_events:
      type: array
      description: list of events candidates
      items:
        $ref: '#/components/schemas/event_match_candidate'

    match_candidates_events_reply:
      type: object
      properties:
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
        candidates:
          type: array
          description: list of events candidates
          items:
            $ref: '#/components/schemas/event_match_candidate_reply'
      required: [label, candidates]

    match_candidates_reply:
      anyOf:
        - $ref: '#/components/schemas/match_candidates_faces_reply'
        - $ref: '#/components/schemas/match_candidates_events_reply'

    match_candidates_new_event_faces:
      type: object
      minItems: 1
      properties:
        candidates:
          $ref: '#/components/schemas/match_candidates_faces'
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
      required: [candidates, label]

    match_candidates_new_event_events:
      type: object
      minItems: 1
      properties:
        candidates:
          $ref: '#/components/schemas/match_candidates_events'
        label:
          $ref: '#/components/schemas/top_matching_candidates_label'
      required: [candidates, label]

    match_candidates_new_event:
      oneOf:
        - $ref: '#/components/schemas/match_candidates_new_event_faces'
        - $ref: '#/components/schemas/match_candidates_new_event_events'

    rect:
      type: object
      description: detection rectangle
      properties:
        x:
          type: integer
          description: detection rectangle x coordinate
        y:
          type: integer
          description: detection rectangle y coordinate
        width:
          type: integer
          description: detection rectangle width
        height:
          type: integer
          description: detection rectangle height
      required: [x, y, width, height]

    basic_attributes:
      type: object
      description: basic attributes
      properties:
        age:
          $ref: '#/components/schemas/age'
        gender:
          $ref: '#/components/schemas/gender'
        ethnicities:
          $ref: '#/components/schemas/ethnic_estimations'

    face_attributes_json:
      type: object
      description: face attributes
      properties:
        basic_attributes:
          $ref: '#/components/schemas/basic_attributes'
        descriptor_data:
          $ref: '#/components/schemas/descriptor_base64_with_version'

    face_attributes_msgpack:
      type: object
      description: face attributes
      properties:
        basic_attributes:
          $ref: '#/components/schemas/basic_attributes'
        descriptor_data:
          $ref: '#/components/schemas/descriptor_binary_with_version'

    body_attributes_json:
      type: object
      description: body attributes
      properties:
        descriptor_data:
          $ref: '#/components/schemas/descriptor_base64_with_version'

    body_attributes_msgpack:
      type: object
      description: body attributes
      properties:
        descriptor_data:
          $ref: '#/components/schemas/descriptor_binary_with_version'

    base_new_event:
      type: object
      description: event.
      properties:
        account_id:
          allOf:
            - type: string
              description: account id.
            - $ref: '#/components/schemas/account_id'
        create_time:
          allOf:
            - type: string
              description: event creation time.
            - $ref: '#/components/schemas/time'
        end_time:
          allOf:
            - type: string
              description: event end time, if it was not set, the system will set it by the time of creation.
            - $ref: '#/components/schemas/time'
        event_id:
          allOf:
            - type: string
              description: event id.
            - $ref: '#/components/schemas/event_id'
        handler_id:
          allOf:
            - type: string
              description: id of the handler, which gave birth to the event.
            - $ref: '#/components/schemas/handler_id'
        external_id:
          allOf:
          - $ref: '#/components/schemas/external_id'
          nullable: true
          default: ""
        user_data:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/user_data'
        source:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/source'
        track_id:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/track_id'
        tags:
          allOf:
            - nullable: true
            - $ref: '#/components/schemas/Tags'
        face:
          allOf:
            - $ref: '#/components/schemas/face'
            - description: face object
            - nullable: true
        matches:
          type: array
          description: matches list
          nullable: true
          items:
            $ref: '#/components/schemas/match_candidates_new_event'
          example:
            [{
               "label": "good guys",
               "candidates": [{
                              "face": {
                                "face_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c6",
                                "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
                                "user_data": "fox1991",
                                "create_time": "2018-08-11T09:11:41.674Z"
                              },
                            similarity: 0.5
                            }]},
             {
               "label": "bad guys",
               "candidates": [{
                              "event": {
                                "event_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7",
                                "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
                                "user_data": "fox1991",
                                "create_time": "2018-08-11T09:11:41.674Z",
                                "handler_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7",
                                "source": "426542d6-5509-4e5b-8a01-e2abd5c0a8c7"
                              },
                            "similarity": 0.3
                            }]}]
        detections:
          type: array
          description: detection list
          items:
            type: object
            properties:
              filename:
                type: string
                description: samples filename
              samples:
                description: a couple of face and body samples - both refer to the same person
                type: object
                properties:
                  face:
                    description: face detection
                    type: object
                    nullable: true
                    properties:
                      sample_id:
                        $ref: '#/components/schemas/sample_id'
                      detection:
                        type: object
                        description: detection
                        properties:
                          rect:
                            $ref: '#/components/schemas/rect'
                    required: [sample_id]
                  body:
                    description: body detection
                    type: object
                    nullable: true
                    properties:
                      sample_id:
                        $ref: '#/components/schemas/sample_id'
                      detection:
                        type: object
                        description: detection
                        properties:
                          rect:
                            $ref: '#/components/schemas/rect'
                    required: [sample_id]
                required: [face, body]
              detect_time:
                $ref: '#/components/schemas/detect_time'
              image_origin:
                $ref: '#/components/schemas/image_origin'
            required: [samples, filename, detect_time]
        location:
          $ref: '#/components/schemas/location'
        aggregate_estimations:
          type: object
          description: aggregated estimations
          properties:
            face:
              type: object
              nullable: false
              description: aggregated face estimations
              properties:
                attributes:
                  type: object
                  nullable: false
                  description: aggregated face attributes
                  properties:
                    liveness:
                      allOf:
                        - description: aggregated liveness result
                        - $ref: '#/components/schemas/liveness_result'
                    emotions:
                      allOf:
                        - description: aggregated emotions result
                        - $ref: '#/components/schemas/emotions'
                    mask:
                      allOf:
                        - description: aggregated mask result
                        - $ref: '#/components/schemas/mask'
              required: [attributes]
          required: [face]
      required: [account_id, create_time, event_id, handler_id]

    new_event_json:
      allOf:
        - $ref: '#/components/schemas/base_new_event'
        - properties:
            face_attributes:
              $ref: '#/components/schemas/face_attributes_json'
            body_attributes:
              $ref: '#/components/schemas/body_attributes_json'

    new_event_msgpack:
      allOf:
        - $ref: '#/components/schemas/base_new_event'
        - properties:
            face_attributes:
              $ref: '#/components/schemas/face_attributes_msgpack'
            body_attributes:
              $ref: '#/components/schemas/body_attributes_msgpack'

    event_for_update_json:
      type: object
      description: event for update
      properties:
        face_attributes:
          $ref: '#/components/schemas/face_attributes_json'
        body_attributes:
          $ref: '#/components/schemas/body_attributes_json'

    event_for_update_msgpack:
      type: object
      description: event for update
      properties:
        face_attributes:
          $ref: '#/components/schemas/face_attributes_msgpack'
        body_attributes:
          $ref: '#/components/schemas/body_attributes_msgpack'

    ethnicities_estimations:
      type: object
      description: ethnicity classifier response.
      properties:
        asian:
          type: number
          format: double
          maximum: 1
          minimum: 0
          description: Asian ethnicity probability.
        indian:
          type: number
          format: double
          maximum: 1
          minimum: 0
          description: Indian ethnicity probability.
        caucasian:
          type: number
          format: double
          maximum: 1
          minimum: 0
          description: Caucasian ethnicity probability.
        african_american:
          type: number
          format: double
          maximum: 1
          minimum: 0
          description: African American ethnicity probability.

    ethnic_estimations:
      type: object
      description: ethnicities estimations
      properties:
        estimations:
          $ref: '#/components/schemas/ethnicities_estimations'
        predominant_ethnicity:
          $ref: '#/components/schemas/predominant_ethnicity'

    getEventStats:
      type: object
      properties:
        targets:
          $ref: '#/components/schemas/targets'
        filters:
          $ref: '#/components/schemas/filters'
        period:
          $ref: '#/components/schemas/periods'
        group_by:
          $ref: '#/components/schemas/group_by'

    emotions_estimations:
      type: object
      properties:
        anger:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: anger probability.
        disgust:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: disgust probability.
        fear:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: fear probability.
        happiness:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: happiness probability.
        neutral:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: neutral face probability.
        sadness:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: sadness probability.
        surprise:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          - description: surprise probability.
      required: [surprise, sadness, neutral, happiness, fear, disgust, anger]
      description: emotion classifier response.
      example: {anger: 0.1, disgust: 0.2, fear: 0.3, happiness: 0.4, neutral: 0.5, sadness: 0.6, surprise: 0.7}

    predominant_emotion:
      type: string
      description: name of predominant emotion.
      enum: [surprise, sadness, neutral, happiness, fear, disgust, anger]

    emotions:
      type: object
      description: emotion
      properties:
        estimations:
          allOf:
            - $ref: '#/components/schemas/emotions_estimations'
            - description: emotion classifier response.
        predominant_emotion:
          $ref: '#/components/schemas/predominant_emotion'
      required: [predominant_emotion, estimations]

    liveness_score:
      allOf:
        - $ref: '#/components/schemas/number01'
      description: |
        The parameter shows the probability of a live person being present in the
        image, i.e. it is not a presentation attack.

        In general, the estimated probability must exceed the theoretical
        threshold of 50%. The value may be increased according to your business rules.
      example: 0.99

    liveness_quality:
      allOf:
        - $ref: '#/components/schemas/number01'
      description: |
        Quality value is a probability of "appropriate image".
        The parameter describes the integral value of image, facial and environmental characteristics.
      example: 1.0

    liveness_prediction:
      type: string
      enum: ["spoof", "real", "unknown"]
      description: prediction that a person in the image is real (not a fake)
      example: "real"

    liveness_result:
      type: object
      description: liveness prediction result
      properties:
        prediction:
          $ref: '#/components/schemas/liveness_prediction'
        estimations:
          type: object
          description: liveness estimations result
          properties:
            score:
              $ref: '#/components/schemas/liveness_score'
            quality:
              $ref: '#/components/schemas/liveness_quality'
          required: [score, quality]
      required: [prediction, estimations]

    mask_estimations:
      type: object
      description: raw mask estimations
      properties:
        medical_mask:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          description: The probability that the `medical mask` exists on the face and is worn properly
        missing:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          description: The probability that the `medical mask` doesn't exist on the face
        occluded:
          allOf:
          - $ref: '#/components/schemas/estimation_not_nullable'
          description: The probability that the face is occluded by other object (not by `medical mask`)
      required: [medical_mask, missing, occluded]
      example: {medical_mask: 0.1, missing: 0.2, occluded: 0.3}

    mask_predominant:
      type: string
      enum: [medical_mask, missing, occluded]
      description: most likely mask state

    mask:
      type: object
      description: estimated face mask state
      properties:
        estimations:
          $ref: '#/components/schemas/mask_estimations'
        predominant_mask:
          $ref: '#/components/schemas/mask_predominant'
      required: [estimations, predominant_mask]

    descriptor_base64_with_version:
      description: Descriptor with descriptor version in the json format.
      type: object
      properties:
        descriptor:
          description: raw descriptor bytes encoded in base64
          type: string
          format: base64
        descriptor_version:
          description: descriptor version
          type: integer
          example: 52
      required: [descriptor, descriptor_version]

    descriptor_binary_with_version:
      description: Raw descriptor with version.
      type: object
      properties:
        descriptor:
          description: raw descriptor bytes
          type: string
          format: binary
        descriptor_version:
          description: descriptor version
          type: integer
          example: 52
      required: [descriptor, descriptor_version]

    empty_string:
      type: string
      enum: [""]
      description: no descriptor found.

    event_deletion_info:
      type: array
      items:
        type: object
        properties:
          event_id:
            $ref: '#/components/schemas/event_id'
          face_samples:
            description: array of face sample ids
            type: array
            items:
              $ref: '#/components/schemas/sample_id'
            minItems: 0
            uniqueItems: true
          body_samples:
            description: array of body sample ids
            type: array
            items:
              $ref: '#/components/schemas/sample_id'
            minItems: 0
            uniqueItems: true
          image_origins:
            description: array of image origins
            type: array
            items:
              $ref: '#/components/schemas/image_origin'
            minItems: 0
            uniqueItems: true
        required: [ event_id ]
      minItems: 0
      maxItems: 10000

    removed_descriptors_event_list:
      type: object
      properties:
        event_ids:
          type: array
          description: event ids which descriptors were removed
          items:
            $ref: '#/components/schemas/event_id'
          maxItems: 10000
      required: [event_ids]

    EventWithSimilarity:
      allOf:
        - $ref: '#/components/schemas/Event'
        - properties:
            similarity:
              $ref: '#/components/schemas/event_similarity'

    EventsWithoutCountWithSimilarity:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventWithSimilarity'

    EventsWithMissingAttributes:
      type: object
      properties:
        events:
          type: array
          items:
            type: object
            properties:
              event_id:
                $ref: '#/components/schemas/event_id'
              samples:
                description: |
                    either face sample ids (for `basic_attributes` or `face_descriptor` kinds) or body sample ids (for
                    `body_descriptor` kind).
                type: array
                items:
                  $ref: '#/components/schemas/sample_id'
            required: [event_id]
          minItems: 0
          maxItems: 1000
      required: [events]

    EventsWithMissingAttributesCount:
      type: object
      properties:
        events_count:
          type: integer
          description: count of events.
          example: 55
      required: [events_count]

    health_ok:
      description: successful healthcheck execution info
      type: object
      properties:
        execution_time:
          type: number
          example: 0.123
          description: request execution time in seconds
      required: [ execution_time ]

    health_errors:
      type: object
      properties:
        errors:
          description: failed healthcheck execution info
          type: array
          items:
            properties:
              component:
                description: component name
                type: string
              error:
                allOf:
                  - description: healthcheck error
                  - $ref: '#/components/schemas/Error'
              status:
                description: component health status
                type: integer
                enum: [ 0, 1 ]
            required: [ component, error, status ]
      required: [ errors ]
      example:
        errors:
          - component: events_db
            error:
              error_code: 0
              desc: Success
              detail: Success
            status: 1
          - component: events_db_migration
            error:
              error_code: 10017
              desc: Database error
              detail: Database connection timeout error
            status: 0
  responses:
    internal_server_error:
      description: internal server error.
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
paths:
  /version:
    get:
      tags:
      - version

      summary: get version
      description: get version of service
      operationId: getVersion

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/version'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/{event_id}:
    parameters:
      - $ref: '#/components/parameters/event_id'

    head:
      tags:
      - events
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/account_id'
      summary: check event
      description: check event existence by id.
      operationId: checkEvent
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '404':
          description: Event not found
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
        '500':
          $ref: '#/components/responses/internal_server_error'

    get:
      tags:
      - events
      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/get_event_target'
      - $ref: '#/components/parameters/account_id'

      summary: get event
      description: |
        get event by id.
        If target is not set, reply will contain all event fields.
      operationId: getEvent
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'target'
        '404':
          description: Event not found
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error_code: 23001
                desc: Object not found
                detail: Event with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
        '500':
          $ref: '#/components/responses/internal_server_error'

    patch:
      tags:
        - events
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/application_json_or_msgpack_content'
        - $ref: '#/components/parameters/account_id'

      summary: patch event
      description: update event by id.
      operationId: patchEvent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/event_for_update_json'
          application/msgpack:
            schema:
              $ref: '#/components/schemas/event_for_update_msgpack'
        required: true
      responses:
        '204':
          description: Update success.
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_json:
                  value:
                    error_code: 12022
                    desc: Bad/incomplete input data
                    detail: "Failed to validate input json. Path: 'face_attributes',  message: face_attributes must be object"
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'account_id'
        '404':
          description: Event not found
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error_code: 23001
                desc: Object not found
                detail: Event with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events:
    get:
      tags:
      - events
      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/get_event_target'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/create_time__gte'
      - $ref: '#/components/parameters/create_time__lt'
      - $ref: '#/components/parameters/end_time__gte'
      - $ref: '#/components/parameters/end_time__lt'
      - $ref: '#/components/parameters/sources'
      - $ref: '#/components/parameters/top_matching_candidates_label'
      - $ref: '#/components/parameters/top_similar_object_ids'
      - $ref: '#/components/parameters/top_similar_external_ids'
      - $ref: '#/components/parameters/top_similar_object_similarity__gte'
      - $ref: '#/components/parameters/top_similar_object_similarity__lt'
      - $ref: '#/components/parameters/age__lt'
      - $ref: '#/components/parameters/age__gte'
      - $ref: '#/components/parameters/gender'
      - $ref: '#/components/parameters/emotions'
      - $ref: '#/components/parameters/masks'
      - $ref: '#/components/parameters/ethnic_groups'
      - $ref: '#/components/parameters/liveness'
      - $ref: '#/components/parameters/face_ids'
      - $ref: '#/components/parameters/event_ids'
      - $ref: '#/components/parameters/event_id__gte'
      - $ref: '#/components/parameters/event_id__lt'
      - $ref: '#/components/parameters/handler_ids'
      - $ref: '#/components/parameters/external_ids'
      - $ref: '#/components/parameters/user_data'
      - $ref: '#/components/parameters/tags'
      - $ref: '#/components/parameters/cities'
      - $ref: '#/components/parameters/areas'
      - $ref: '#/components/parameters/districts'
      - $ref: '#/components/parameters/streets'
      - $ref: '#/components/parameters/house_numbers'
      - $ref: '#/components/parameters/origin_longitude'
      - $ref: '#/components/parameters/origin_latitude'
      - $ref: '#/components/parameters/longitude_delta'
      - $ref: '#/components/parameters/latitude_delta'
      - $ref: '#/components/parameters/track_ids'
      - $ref: '#/components/parameters/search_order'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/page_size'

      summary: get events
      description: |
        Get events that satisfy filters.

        Default filters for events:

          - `create_time__lt` - current datetime
          - `create_time__gte` - current datetime minus month

          > **Default filters are not used if any of the following parameters are defined**:

            - list of event IDs (`event_ids`)
            - lower event ID boundary (`event_id__gte`)
            - upper event ID boundary (`event_id__lt`)
            - lower create time boundary (`create_time__gte`)
            - upper create time boundary (`create_time__lt`)

        The `target` parameter determines field that will be shown for each event.
        If target is not set, the response will contain all the fields, except the descriptor data.

        To count events, use <a href="#tag/events-stats">"get statistics on events"</a> request.
      operationId: getEvents
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsWithoutCount'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'create_time__lt'
        '500':
          $ref: '#/components/responses/internal_server_error'

    post:
      tags:
      - events
      summary: create new events
      description: creates new events.
      operationId: createEvents
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/application_json_or_msgpack_content'
        - $ref: '#/components/parameters/wait_events_saving'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/new_event_json'
              minItems: 1
          application/msgpack:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/new_event_msgpack'
              minItems: 1
        required: true
      responses:
        '202':
          description: Events data is received. Events will be saved to the database soon.
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '204':
          description: events were created and stored in the database.
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '400':
          description: bad request.
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_json:
                  value:
                    error_code: 12022
                    desc: Bad/incomplete input data
                    detail: '[0].create_time,  message: ''incorrect time format'''
        '409':
          description: event already exists
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                duplicated_id:
                  value:
                    error_code: 23003
                    desc: Unique constraint error
                    detail: "One or more event id from '1231531' already exist"
        '500':
          description: internal server error.
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                events_saving_error:
                  value:
                    error_code: 23010
                    desc: internal server error
                    detail: Unknown error
                save_events_timeout:
                  value:
                    error_code: 23007
                    desc: Internal server error
                    detail: Timeout (5 seconds) for save events into history database has been expired
                common_error:
                  value:
                    error_code: 1
                    detail: internal server error
                    desc: internal server error

    delete:
      tags:
      - events
      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/delete_event_target'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/handler_id'
      - $ref: '#/components/parameters/create_time__gte'
      - $ref: '#/components/parameters/create_time__lt'
      - $ref: '#/components/parameters/insert_time__gte'
      - $ref: '#/components/parameters/insert_time__lt'

      summary: delete events
      description: delete oldest 10000 events that satisfy filters.
      operationId: deleteEvents
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event_deletion_info'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'handler_id'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/attributes/missing:
    get:
      tags:
      - administration
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/kind'
      - $ref: '#/components/parameters/insert_time__gte'
      - $ref: '#/components/parameters/insert_time__lt'
      - $ref: '#/components/parameters/event_id__gte'
      - $ref: '#/components/parameters/event_id__lt'
      - $ref: '#/components/parameters/handler_id'
      - $ref: '#/components/parameters/missing_version'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/page_size'

      summary: get events with missing attributes
      description: |
        Get events with samples and with missing attributes that satisfy filters.

      operationId: getEventsMissing
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsWithMissingAttributes'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'insert_time__lt'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/attributes/missing/count:
    get:
      tags:
      - administration
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/kind'
      - $ref: '#/components/parameters/insert_time__gte'
      - $ref: '#/components/parameters/insert_time__lt'
      - $ref: '#/components/parameters/event_id__gte'
      - $ref: '#/components/parameters/event_id__lt'
      - $ref: '#/components/parameters/handler_id'
      - $ref: '#/components/parameters/missing_version'

      summary: get count of events with missing attributes
      description: |
        Get count of events with samples and with missing attributes that satisfy filters.

      operationId: getEventsMissingCount
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsWithMissingAttributesCount'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'insert_time__lt'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/descriptors:
    delete:
      tags:
      - administration
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/event_id__gte'
      - $ref: '#/components/parameters/event_id__lt'
      - $ref: '#/components/parameters/descriptor_version_required'
      - $ref: '#/components/parameters/descriptor_type_required'

      summary: delete events descriptors
      description: Delete 10000 event descriptors that satisfy filters.

      operationId: deleteDescriptors
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/removed_descriptors_event_list'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'event_id__lt'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/{event_id}/descriptor:
    parameters:
      - $ref: '#/components/parameters/event_id'

    get:
      tags:
      - event descriptor
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/descriptor_version'
      - $ref: '#/components/parameters/descriptor_type'

      summary: get event descriptor
      description: Get event descriptor that corresponds to the specified parameters.
      operationId: getEventDescriptor
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json_or_xbinary'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/descriptor_base64_with_version'
            application/x-sdk-descriptor:
              schema:
                type: string
                format: binary
                description: content type is application/x-sdk-descriptor, a binary descriptor is returned in the response body
              example: "<a binary descriptor in the SDK format>"
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'descriptor_version'
        '404':
          description: object not found
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                event_not_found:
                  value:
                    error_code: 23001
                    desc: Object not found
                    detail: Event with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found
                face_descriptor_not_found:
                  value:
                    error_code: 22018
                    desc: Object not found
                    detail: Face descriptor of version 7 is not found for object with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37'.
                human_descriptor_not_found:
                  value:
                    error_code: 23007
                    desc: Object not found
                    detail: Human descriptor of version 7 is not found for object with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37'.
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/stats:
    post:
      tags:
      - events stats
      summary: get statistics on events
      description: |
        Get event statistics by target(s) with applied filters.

        Event fields and/or functions (count, min, etc.) can be set as targets for aggregation of events.

        Grouping by frequency or grouping by time intervals is available.
      operationId: getEventStats
      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/applicationJsonContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/getEventStats'
            example:
              targets:
                - column: event_id
                  aggregator: count
                - column: age
                  aggregator: group_by
                - column: gender
                  aggregator: group_by
              filters:
                - column: source
                  operator: eq
                  value: Main_hall_camera
                - column: geo_position
                  operator: covered
                  value:
                    origin_longitude: 37
                    origin_latitude: 55
                    longitude_delta: 0.04
                    latitude_delta: 0.04

              period:
                - operator: gt
                  value: 2020-02-04T00:00:00Z
                - operator: lt
                  value: 2020-02-06T00:00:00Z
              group_by: dayOfWeek
        required: true
      responses:
        '200':
          description: Created
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      type: string
                    description: |
                      reply structure description includes is as follows:
                      - First element of a list is 'Group by time' section if request includes time or frequency grouping.
                      - Other elements are pairs of columns and aggregators for the columns.

                      List of columns and aggregators presents in the same order as in stats.
                  stats:
                    type: array
                    items:
                      anyOf:
                        - type: integer
                        - type: number
                        - type: string
                        - type: array
                    description: any type of items
              examples:
                count_dayOfWeek:
                  value:
                    fields:
                      - "Group by time: dayOfWeek"
                      - "gender, aggregator 'group_by'"
                      - "age, aggregator 'group_by'"
                      - "event_id, aggregator 'count'"
                    stats:
                    - - Tuesday
                      - 0
                      - 22
                      - 45
                    - - Tuesday
                      - 0
                      - 27
                      - 23
                    - - Tuesday
                      - 1
                      - 27
                      - 45
                    - - Wednesday
                      - 0
                      - 25
                      - 34
                    - - Wednesday
                      - 1
                      - 33
                      - 345

        '400':
          description: Bad request
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_json:
                  value:
                    error_code: 12022
                    desc: Bad/incomplete input data
                    detail: 'Failed to validate input json. Path: '''',  message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/events/match:
    post:
      tags:
      - events match
      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/post_event_match_target'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/create_time__gte'
      - $ref: '#/components/parameters/create_time__lt'
      - $ref: '#/components/parameters/end_time__gte'
      - $ref: '#/components/parameters/end_time__lt'
      - $ref: '#/components/parameters/sources'
      - $ref: '#/components/parameters/top_matching_candidates_label'
      - $ref: '#/components/parameters/top_similar_object_ids'
      - $ref: '#/components/parameters/top_similar_external_ids'
      - $ref: '#/components/parameters/top_similar_object_similarity__gte'
      - $ref: '#/components/parameters/top_similar_object_similarity__lt'
      - $ref: '#/components/parameters/age__lt'
      - $ref: '#/components/parameters/age__gte'
      - $ref: '#/components/parameters/gender'
      - $ref: '#/components/parameters/emotions'
      - $ref: '#/components/parameters/masks'
      - $ref: '#/components/parameters/ethnic_groups'
      - $ref: '#/components/parameters/liveness'
      - $ref: '#/components/parameters/face_ids'
      - $ref: '#/components/parameters/event_ids'
      - $ref: '#/components/parameters/event_id__gte'
      - $ref: '#/components/parameters/event_id__lt'
      - $ref: '#/components/parameters/handler_ids'
      - $ref: '#/components/parameters/external_ids'
      - $ref: '#/components/parameters/user_data'
      - $ref: '#/components/parameters/tags'
      - $ref: '#/components/parameters/cities'
      - $ref: '#/components/parameters/areas'
      - $ref: '#/components/parameters/districts'
      - $ref: '#/components/parameters/streets'
      - $ref: '#/components/parameters/house_numbers'
      - $ref: '#/components/parameters/origin_longitude'
      - $ref: '#/components/parameters/origin_latitude'
      - $ref: '#/components/parameters/longitude_delta'
      - $ref: '#/components/parameters/latitude_delta'
      - $ref: '#/components/parameters/track_ids'
      - $ref: '#/components/parameters/match_order'
      - $ref: '#/components/parameters/threshold'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/descriptor_type'

      summary: match events
      description: |
        Match events that satisfy filters.

        Default filters for match events:

          - `create_time__lt` - current datetime
          - `create_time__gte` - current datetime minus month

          > **Default filters are not used if any of the following parameters are defined**:

            - list of event IDs (`event_ids`)
            - lower event ID boundary (`event_id__gte`)
            - upper event ID boundary (`event_id__lt`)
            - lower create time boundary (`create_time__gte`)
            - upper create time boundary (`create_time__lt`)

        If target is not set, the response will contain events with "event_id" and "similarity" fields only.

        To count events, use <a href="#tag/events-stats">"get statistics on events"</a> request.
      operationId: matchEvents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/descriptor_base64_with_version'
          application/x-sdk-descriptor:
            schema:
              description: Descriptor in the SDK format.
              type: string
              format: binary
        required: true
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsWithoutCountWithSimilarity'
        '400':
          description: bad request
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad_query_param:
                  value:
                    error_code: 12012
                    desc: Bad/incomplete input data
                    detail: Bad query parameters 'create_time__lt'
        '403':
          description: Forbidden
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
            Content-Type:
              $ref: '#/components/headers/application_json'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error_code: 12029
                desc: Functionality is not implemented
                detail: Required server functionality is not implemented
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/docs/spec:
    get:
      tags:
        - documents
      summary: get openapi documentation
      description: |
        Get service OpenApi documentation. If *Accept* request header is of type `application/x-yaml`,
        returns documentation in `yaml` format or returns `html` documentation, if *Accept-Type* is `text/html`
      operationId: getSpec

      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/accept_docs_handler'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/docs_content_type'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/x-yaml:
              schema:
                type: string
                description: yaml format documentation
            text/html:
              schema:
                type: string
                description: html format documentation
        '415':
          description: Unsupported Media Type
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unsupported_media_type:
                  value:
                    error_code: 12024
                    detail: 'Bad/incomplete input data'
                    desc: "Unsupported media type"
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/docs/dev:
    get:
      tags:
        - documents
      summary: get development manual
      description: |
        Get sphinx documentation - *Development Manual*. After the request you will be redirected to the page `/docs/dev/index.html`
      operationId: getDevManual

      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/text_html'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            text/html:
              schema:
                type: string
                description: html format documentation
        '500':
          $ref: '#/components/responses/internal_server_error'
  /2/config:
    get:
      tags:
        - config
      summary: get service configuration
      description: Get service configuration. Passwords and tokens will be hidden in the response.
      operationId: getConfig

      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/accept_config_handler'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/config_accept_content_type'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                type: object
                description: json format configuration
              example:
                INFLUX_MONITORING:
                  SEND_DATA_FOR_MONITORING: 0
                  VERSION: 2
                  ORGANIZATION: ORGANIZATION_NAME
                  TOKEN: '********'
                  BUCKET: luna_monitoring
                  HOST: 127.0.0.1
                  PORT: 8086
                  USE_SSL: 0
                  FLUSHING_PERIOD: 1.0
            text/plain:
              schema:
                type: string
                description: text format configuration
              example: |
                [INFLUX_MONITORING]
                SEND_DATA_FOR_MONITORING = 0
                VERSION = 2
                ORGANIZATION = ORGANIZATION_NAME
                TOKEN = ********
                BUCKET = luna_monitoring
                HOST = 127.0.0.1
                PORT = 8086
                USE_SSL = 0
                FLUSHING_PERIOD = 1.0
        '415':
          description: Unsupported Media Type
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unsupported_media_type:
                  value:
                    error_code: 12024
                    detail: 'Bad/incomplete input data'
                    desc: "Unsupported media type"
        '500':
          $ref: '#/components/responses/internal_server_error'
  /healthcheck:
    get:
      tags:
      - health
      summary: get health
      description: get health of service
      operationId: healthcheck
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health_ok'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '502':
          description: Unhealthy
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health_errors'
