openapi: 3.1.0
info:
  version: v.0.0.3
  title: Luna Vector Search Module API
  description: Service for vector search across user-defined collections.

components:
  headers:
    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_json:
      schema:
        type: string
        enum:
        - application/json
      required: true
      description: The content type of the response body.

    text_html:
      schema:
        type: string
        enum:
          - text/html
      required: true
      description: The content type of the response body.
  parameters:
    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: request identifier.
      name: Luna-Request-Id

    include_luna_services:
      in: query
      name: include_luna_services
      schema:
        type: integer
        enum: [0, 1]
        default: 0
      description: whether to perform healthchecks for dependent luna services.
  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'

    server_timeout_error:
      description: server timeout error.
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/error'
            example:
              error_code: 9
              detail: Request timeout
              desc: Request timeout on http://127.0.0.1:5100/{...}, method {...}
              link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-9

    forbidden_resource_error:
      description: Forbidden
      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:
            resource_is_disabled:
              value:
                error_code: 12049
                desc: Forbidden
                detail: Resource is disabled.
                link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12049"

    forbidden_error:
      description: Forbidden
      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_disabled:
              value:
                error_code: 11040
                desc: Forbidden
                detail: Luna Events service is disabled
                link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-11040
  schemas:
    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 ]

    error:
      type: object
      properties:
        error_code:
          type: integer
          description: Error code.
        desc:
          type: string
          description: Short error description.
        detail:
          type: string
          description: Error details.
        link:
          type: string
          description: Link to the documentation website with the error description.
      required: [error_code, detail, desc, link]
      example:
        error_code: 1
        detail: Internal server error
        desc: Internal server error
        link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-1

    plugin_status:
      type: object
      properties:
        name:
          type: string
          description: Plugin name
        running:
          type: integer
          enum: [0,1]
          description: Whether plugin is running or not.
      required: [name, running]

    plugins:
      type: object
      properties:
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/plugin_status'
      description: List of imported plugins

    platt_scaling:
      type: object
      nullable: true
      properties:
        a:
          type: number
          description: the left normalizing number
          example: 1
        b:
          type: number
          description: the right normalizing number
          example: -0.217
      description: >
        Data for normalization of the scores obtained during the matching.
        When omitted, the default value registered in the system will be used.

    descriptor_config:
      type: object
      properties:
        descriptor_type:
          type: string
          enum: ["face", "body"]
          description: type of descriptor
          example: face
        descriptor_version:
          type: integer
          description: version of descriptor
          example: 65
        platt_scaling:
          $ref: '#/components/schemas/platt_scaling'
      required:
        - descriptor_type
        - descriptor_version
      example:
        descriptor_type: face
        descriptor_version: 65

    registered_descriptor_config:
      type: object
      properties:
        object_type:
          type: string
          enum: ["events"]
        dtype:
          type: string
          enum: ["face", "body"]
          description: type of descriptor
          example: face
        version:
          type: integer
          description: version of descriptor
          example: 65
        platt_scaling:
          $ref: '#/components/schemas/platt_scaling'
        length:
          type: integer
          description: length of descriptor
          example: 512
      required:
        - dtype
        - version
        - platt_scaling
        - length
        - object_type


    event_targets:
      type: array
      description: Luna Platform supported event targets to be placed to the collection payload
      items:
        type: string
        enum: [
          event_id,
          account_id,
          create_time,
          end_time,
          handler_id,
          face_id,
          external_id,
          source,
          stream_id,
          top_match,
          match_result,
          face_detections,
          body_detections,
          attach_result,
          gender,
          age,
          emotion,
          ethnic_group,
          tags,
          user_data,
          location,
          mask,
          track_id,
          liveness,
          deepfake,
          body_basic_attributes,
          upper_body,
          lower_body,
          accessories,
          meta,
        ]
      minItems: 1

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

    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"

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

    source:
      type: string
      description: some additional information that user provides with event.
      example: "3rd Avenue"
      nullable: true

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

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

    similarity:
      type: number
      minimum: 0
      maximum: 1
      example: 0.5

    field_external_id:
      description: user-defined external id for face.
      type: string
      maxLength: 36
      example: "2xQ2gprbMUePw1s9gw9fvA=="
      default: ""

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

    mask_enum:
      description: |
        predominant mask.

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

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

    liveness_enum:
      description: |
        predominant liveness.

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

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

    deepfake_enum:
      description: |
        predominant deepfake.

        | deepfake | value |
        |--------------|---|
        | fake         | 0 |
        | real         | 1 |

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

    ethnic_group:
      type: integer
      enum: [1,2,3,4,null]

    age:
      type: integer
      minimum: 0
      maximum: 100
      description: age upper excluded bound.
      example: 50

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

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

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

    object_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: match object id (face id or event id).

    filter_external_id:
      description: objects whose `external_id` values are not equal to the filter will be filtered
      type: string
      maxLength: 36
      example: "2xQ2gprbMUePw1s9gw9fvA=="

    face_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
      description: face id
      example: "557d54ec-29ad-4f3c-93b4-c9092ef12515"

    event_conditions:
      type: object
      description: Luna Platform supported filters to be applied as conditions by which the collection is built. When no filters specified, all the entities will be placed in the collection
      properties:
        account_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: id of the luna account.
          example: b668c4a5-2191-476e-a261-3b4f9ce2e25e
        event_ids:
          type: array
          items:
            $ref: '#/components/schemas/event_id'
          description: list of event ids associated with face
          minItems: 1
        event_id__gte:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: event id lower included boundary
          example: b668c4a5-2191-476e-a261-3b4f9ce2e25e
        event_id__lt:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: event id upper excluded boundary
          example: b668c4a5-2191-476e-a261-3b4f9ce2e25e
        create_time__gte:
          allOf:
            - $ref: '#/components/schemas/time'
          description: create time lower included boundary
        create_time__lt:
          allOf:
            - $ref: '#/components/schemas/time'
          description: create time upper excluded boundary
        end_time__gte:
          allOf:
            - $ref: '#/components/schemas/time'
          description: end time lower included boundary
        end_time__lt:
          allOf:
            - $ref: '#/components/schemas/time'
          description: end time upper excluded boundary
        external_ids:
          type: array
          items:
            $ref: '#/components/schemas/filter_external_id'
          description: list of external ids. Each event from result will contain one of the given external ids.
          minItems: 1
        face_ids:
          type: array
          items:
            $ref: '#/components/schemas/face_id'
          description: list of face ids
          minItems: 1
        user_data:
          description: user data filter. Objects whose `user_data` values are not contain the filter will be filtered
          type: string
          example: "100-00-12"
        sources:
          type: array
          items:
            $ref: '#/components/schemas/source'
          description: list of sources. Each event from result will contain one of the given sources in location.
          example: ['cam1', 'cam2']
          minItems: 1
        stream_ids:
          type: array
          items:
            $ref: '#/components/schemas/stream_id'
          description: list of stream ids. Each event from result will contain one of the given stream ids.
          minItems: 1
        handler_ids:
          type: array
          items:
            $ref: '#/components/schemas/handler_id'
          description: list of handler ids. Each event from result will contain one of the given handler ids.
          minItems: 1
        top_matching_candidates_label:
          description: top matching candidates label.
          type: string
          example: good guys
        top_similar_object_similarity__gte:
          allOf:
            - $ref: '#/components/schemas/similarity'
          description: top similar object similarity lower included bound.
        top_similar_object_similarity__lt:
          allOf:
            - $ref: '#/components/schemas/similarity'
          description: top similar object similarity upper excluded bound.
        top_similar_external_ids:
          type: array
          items:
            $ref: '#/components/schemas/field_external_id'
          description: list of top similar external ids. Each event from result will contain one of the given similar external ids.
          minItems: 1
        tags:
          description: list of tags.
          type: array
          items:
            type: string
          example: ['tag1', 'tag2']
          minItems: 1
        emotions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/emotion'
          description: |
            list of 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, 4]
        masks:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/mask_enum'
          description: |
            list of masks. Each event from result will contain one of the given mask states.

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

          example: "2,3"
        liveness:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/liveness_enum'
          description: |
            list of liveness. Each event from result will contain one of the given liveness.

            | liveness | value |
            |--------------|---|
            | spoof        | 0 |
            | real         | 1 |
            | unknown      | 2 |
        deepfake:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/deepfake_enum'
          description: |
            list of deepfake. Each event from result will contain one of the given deepfake.

            | deepfake | value |
            |--------------|---|
            | fake         | 0 |
            | real         | 1 |
        ethnic_groups:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ethnic_group'
          description: |
            list of ethnic group. Each event from result will contain one of the given ethnic groups.

            | ethnicity   | value |
            |-----------------|---|
            | AfricanAmerican | 1 |
            | Indian          | 2 |
            | Asian           | 3 |
            | Caucasian       | 4 |
        gender:
          type: integer
          enum: [0, 1]
          description: gender, 0 - female, 1 - male
        age__gte:
          allOf:
            - $ref: '#/components/schemas/age'
          description: age lower included bound.
        age__lt:
          allOf:
            - $ref: '#/components/schemas/age'
          description: age upper excluded bound.
        apparent_gender:
          type: array
          minItems: 1
          items:
            type: integer
            enum: [ 0, 1, 2, null]
          description: |
            Apparent gender filter: 0 - female, 1 - male, 2 - undefined. Each event from result will contain one of the given states.
          example: [ 1 ]
        apparent_age__lt:
          type: integer
          description: Apparent age upper excluded bound.
          example: 50
        apparent_age__gte:
          type: integer
          description: Apparent age lower included bound.
          example: 50
        headwear_states:
          type: array
          minItems: 1
          items:
            type: integer
            enum: [ 0, 1, 2, null]
          description: |
          Headwear state filter: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.
          example: [ 1 ]
        headwear_apparent_colors:
          type: array
          minItems: 1
          items:
            type: string
            enum: ["undefined", "black", "white", "other", null]
            description: Headwear apparent color.
          description: |
            Headwear apparent color filter. Each event from result will contain one of the given states.
          example: [ "black" ]
        sleeve_lengths:
          type: array
          minItems: 1
          items:
            type: string
            enum: ["short", "long", "undefined", null]
          description: |
            Sleeve length state filter. Each event from result will contain one of the given states.
          example: [ "short" ]
        upper_clothing_colors:
          type: array
          minItems: 1
          items:
              type: string
              enum: [ "undefined", "black", "blue", "green", "gray", "orange", "purple", "red", "white", "yellow", "pink", "brown", "beige", "khaki", "multicolored", null]
              description: Clothing color.
          description: |
            Upper clothing color filter. Each event from result will contain at least one of the given clothing colors.
          example: [ "black", "blue" ]
        lower_garment_types:
          type: array
          minItems: 1
          items:
            type: string
            enum: ["undefined", "trousers", "shorts", "skirt", null]
          description: |
            Lower garment type filter. Each event from result will contain one of the given states.
          example: [ "trousers" ]
        lower_garment_colors:
          type: array
          minItems: 1
          items:
              type: string
              enum: [ "undefined", "black", "blue", "green", "gray", "orange", "purple", "red", "white", "yellow", "pink", "brown", "beige", "khaki", "multicolored", null]
              description: Clothing color.
          description: |
            Lower garment color filter. Each event from result will contain at least one of the given clothing colors.
          example: [ "green", "gray" ]
        shoes_apparent_colors:
          type: array
          minItems: 1
          items:
            type: string
            enum: ["undefined", "black", "white", "other", null]
            description: Shoes apparent color.
            nullable: true
          description: |
            Shoes apparent color filter. Each event from result will contain one of the given states.
          example: [ "white" ]
        backpack_states:
          type: array
          minItems: 1
          items:
            type: integer
            enum: [ 0, 1, 2, null]
          description: |
            Backpack state filter: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.
          example: [ 1 ]
        track_ids:
          type: array
          items:
            $ref: '#/components/schemas/track_id'
          description: list of track ids. Each event from result will contain one of the given track ids.
          minItems: 1
        cities:
          type: array
          items:
            type: string
            maxLength: 36
          description: List of cities. Each event from result will contain one of the given cities in location.
          example: ["moscow", "New-York"]
          minItems: 1
        districts:
          type: array
          items:
            type: string
            maxLength: 36
          description: List of districts. Each event from result will contain one of the given districts in location.
          example: ["mitino", "central park"]
          minItems: 1
        streets:
          type: array
          items:
            type: string
            maxLength: 36
          description: List of streets. Each event from result will contain one of the given streets in location.
          example: ["arbat, schepkina"]
          minItems: 1
        house_numbers:
          type: array
          items:
            type: string
            maxLength: 36
          description: List of house numbers. Each event from result will contain one of the given house numbers in location.
          example: ["1", "1/2str3"]
          minItems: 1
        areas:
          description: List of areas. Each event from result will contain one of the given areas in location.
          type: array
          items:
            type: string
            maxLength: 36
          example: ['area1', 'area2']
          minItems: 1
          maxItems: 1000
        geo_position:
          type: object
          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
          nullable: true
          required: [origin_longitude, origin_latitude]
        top_similar_object_ids:
          type: array
          items:
            $ref: '#/components/schemas/object_id'
          description: list of top similar object ids. Each event from result will contain one of the given similar object ids.
          minItems: 1
          maxItems: 1000

    events_collection:
      type: object
      properties:
        object_type:
          type: string
          description: Entity type for which the collection is built
          enum: ["events"]
        descriptors:
          type: array
          description: Descriptor paramaters for which the collection is built
          items:
            $ref: '#/components/schemas/descriptor_config'
        payload:
          $ref: '#/components/schemas/event_targets'
        conditions:
          $ref: '#/components/schemas/event_conditions'
        description:
          type: string
          nullable: true
          description: description of the collection
      required:
        - object_type
        - descriptors
        - payload
        - conditions

    collection_meta:
      type: object
      properties:
        parameters:
          oneOf:
            - $ref: '#/components/schemas/events_collection'
        max_link_key:
          type: integer
          description: the maximum id of a saved object in the collection
        max_unlink_key:
          type: integer
          description: the maximum id of a deleted object in the collection
        sync_time:
          type: string
          format: date-time
          nullable: true
          description: the time of the last synchronization of the collection
        collection_name:
          type: string
          description: name of collection
        description:
          type: string
          nullable: true
          description: description of the collection
      required:
        - parameters
        - max_link_key
        - max_unlink_key
        - sync_time
        - collection_name
        - description

paths:

  /1/collections:
    parameters:
        - $ref: '#/components/parameters/luna_request_id'
    
    post:
      tags: [ collections ]
      
      summary: create collection
      description: >
        Creates a collection and assigns a caretaker to it, which performs the initial filling
        of the collection and subsequent periodic synchronization with external data sources.
      operationId: createCollection

      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/events_collection'
      responses:
        '201':
          description: OK
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection_id:
                    type: string
                    description: new collection ID
                    example: '6383755390710280921'
                required: [ collection_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:
                object_type:
                  value:
                      error_code: 12022
                      desc: Bad/incomplete input data
                      detail: 'Failed to validate input json. Path: ''object_type'',  message: ''object_type must be one of [''events'']'
                      link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022
        '403':
            $ref: '#/components/responses/forbidden_error'
        '409':
          description: Conflict
          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:
                collection_conflict:
                  value:
                    error_code: 50001
                    desc: Collection exists
                    detail: 'Collection with the specified parameters already exists, its id is ''6383755390710280921'''
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-50001
                descriptor_conflict:
                  value:
                    error_code: 50002
                    desc: Access to an unregistered descriptor
                    detail: 'There are no registered settings for descriptor: object_type=events, descriptor_type=face, descriptor_version=116'
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-50002
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'

    get:
      tags: [ collections ]

      summary: get collections
      description: Get collection data and configs of registered descriptors
      operationId: getCollections

      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:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      $ref: '#/components/schemas/collection_meta'
                required: [ collections ]
        '403':
            $ref: '#/components/responses/forbidden_error'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/collections/{collection_id}:
    parameters:
    - in: path
      name: collection_id
      schema:
        type: string
      required: true
      description: ID of the collection (`collection_id` received in the "create collection" request)
    - $ref: '#/components/parameters/luna_request_id'
    
    delete:
      tags: [ collections ]
      
      summary: remove collection
      description: >
        Unregister collection by ID
      operationId: removeCollection

      responses:
        '204':
          description: OK
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '404':
          description: Collection not found
          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:
                collection_not_found:
                  value:
                    error_code: 50006
                    desc: Object not found
                    detail: 'Collection with id ''6383755390710280921'' not found'
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-50006
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'

    patch:
      tags: [ collections ]
      summary: patch collection
      description: >
        Update collection description by its ID
      operationId: patchCollection

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  nullable: true
                  description: new description of the collection
              required:
                - description

      responses:
        '204':
          description: OK
          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:
                object_type:
                  value:
                      error_code: 12022
                      desc: Bad/incomplete input data
                      detail: 'Failed to validate input json. Path: ''object_type'',  message: ''object_type must be one of [''events'']'
                      link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022
        '404':
          description: Collection not found
          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:
                collection_not_found:
                  value:
                    error_code: 50006
                    desc: Object not found
                    detail: 'Collection with id ''6383755390710280921'' not found'
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-50006
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/descriptors:
    get:
      tags: [ descriptors ]

      summary: get descriptor configs
      description: >
        Get the descriptor settings registered in the system. Based on this data,
        the parameters of the vectors of the created collections are calculated,
        and some of this data is used as default values if no `platt_scaling`
        value is specified when creating the collection.

      operationId: getDescriptors

      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:
                type: object
                properties:
                  descriptor_configs:
                    type: array
                    items:
                      $ref: '#/components/schemas/registered_descriptor_config'
                required: [ descriptor_configs ]
        '403':
            $ref: '#/components/responses/forbidden_error'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /version:
    get:
      tags:
      - version

      summary: get version
      description: get service version
      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'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/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'
        - name: Accept
          in: header
          schema:
            type: string
            enum:
              - application/x-yaml
              - text/html
            description: One of application/x-yaml, text/html
          required: true
          description: acceptable type of receiving data
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                enum:
                  - application/x-yaml
                  - text/html
              required: true
              description: The content type of the response body.
            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
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12024
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/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'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/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'
        - name: Accept
          in: header
          schema:
            type: string
            enum:
              - application/json
              - text/plain
            description: One of application/json, text/plain
          required: false
          description: acceptable type of receiving data
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              description: The content type of the response body.
              schema:
                type: string
                enum:
                  - application/json
                  - text/plain
              required: true
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                type: object
                description: json format configuration
                additionalProperties: true
              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
                    link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12024
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /1/plugins:
    get:
      tags:
        - plugins
      summary: get list of plugins
      description: |
        Get list of service plugins:
      operationId: getPlugins
      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/plugins'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /metrics:

    get:
      tags:
        - metrics
      summary: get service requests statistics
      description: Get statistics of success and failed requests to the service in prometheus format.
      operationId: metrics
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      responses:
        '200':
          description: OK.
          headers:
            Content-Type:
              schema:
                type: string
                enum:
                  - text/plain; charset=UTF-8
              required: true
              description: Content type is `text/plain`.
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            text/plain:
              schema:
                type: string
                description: Prometheus plain text format.
              example: |
                # HELP request_count_total Counter of requests
                # TYPE request_count_total counter
                request_count_total{path="GET:/healthcheck",status_code="200"} 1.0
        '403':
          $ref: '#/components/responses/forbidden_resource_error'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '504':
          $ref: '#/components/responses/server_timeout_error'
  /healthcheck:
    get:
      tags:
      - health
      summary: get health
      description: get health of service
      operationId: healthcheck
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/include_luna_services'
      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:
                description: successful healthcheck execution info
                type: object
                properties:
                  execution_time:
                    type: number
                    example: 0.123
                    description: request execution time in seconds
                required: [ execution_time ]
        '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:
                type: object
                properties:
                  errors:
                    description: failed healthcheck execution info
                    type: array
                    items:
                      type: object
                      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: db
                      error:
                        error_code: 0
                        desc: Success
                        detail: Success
                        link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0
                      status: 1
                    - component: events_db
                      error:
                        error_code: 38001
                        desc: Health check error
                        detail: Database connection timeout error
                        link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0
                      status: 0
        '504':
          $ref: '#/components/responses/server_timeout_error'
x-tagGroups:
- name: Indexing
  tags:
  - collections
  - descriptors
- name: Sys
  tags:
  - documents
  - config
  - plugins
  - metrics
  - health
  - version
