openapi: 3.1.0
info:
  version: v.0.4.0
  title: Luna Indexed Matcher API
  description: Service is intended for indexing matching.
paths:
  /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'
  /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'
  /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'
  /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
            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'
  /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:
                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: redis
                      error:
                        error_code: 0
                        desc: Success
                        detail: Success
                        link: >-
                          https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0
                      status: 0
  /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'
  /1/indexes:
    get:
      tags:
        - indexes
      summary: get indexes
      description: Get indexes available for search by.
      operationId: getIndexes
      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:
                  indexes:
                    type: array
                    items:
                      $ref: '#/components/schemas/index'
                    description: Set of indexes loaded into matcher memory.
                required:
                  - indexes
        '500':
          $ref: '#/components/responses/internal_server_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/parameters_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'
components:
  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
  headers:
    application_json:
      schema:
        type: string
        enum:
          - application/json
      required: true
      description: The content type of the response body.
    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
    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
  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
    descriptor_version:
      type: integer
      description: Version of descriptors which used for index building.
      example: 59
    index_config:
      type: object
      properties:
        descriptor_version:
          $ref: '#/components/schemas/descriptor_version'
        ef_construction:
          description: Index construction speed/accuracy ratio.
          type: integer
      required:
        - descriptor_version
        - ef_construction
      example:
        descriptor_version: 59
        ef_construction: 1600
    index_refresh_state:
      type: object
      properties:
        max_link_key:
          description: Max indexing set link key.
          type: integer
          nullable: true
        max_unlink_key:
          description: Max indexing set unlink key.
          type: integer
          nullable: true
        removed_count:
          description: >-
            Number of descriptors marked unavailable for search while index
            refreshing due to removal from indexing set.
          type: integer
      required:
        - max_link_key
        - max_unlink_key
        - removed_count
      example:
        max_link_key: 123000
        max_unlink_key: 1230
        removed_count: 123
    index:
      type: object
      properties:
        index_type:
          type: string
          enum:
            - list
        label:
          type: string
          description: >-
            Matching label, i.e. some indexing set ID. For face list indexing
            the label is always list ID.
          example: 8dac9450-916f-418f-99d2-7b2678b3f9cd
        index_id:
          type: string
          description: Index unique ID; corresponds to the indexing task ID if specified.
          example: 75d2d935-2007-4d2c-bf01-e3f12a69dac3
        account_id:
          type: string
          description: Index owner account ID.
          example: 9c05c658-e57f-469b-8500-5e19e3a09274
        config:
          $ref: '#/components/schemas/index_config'
        refresh_state:
          $ref: '#/components/schemas/index_refresh_state'
      required:
        - index_type
        - label
        - index_id
        - account_id
        - config
        - refresh_state
  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'
    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
