openapi: 3.1.0
info:
  version: v.0.4.0
  title: Luna Indexer API
  description: Service for indexing descriptors.
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/state:
    get:
      tags: []
      summary: get state
      description: Returns current state of the indexer
      operationId: getState
      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/state'
        '500':
          $ref: '#/components/responses/internal_server_error'
  /1/index_list:
    post:
      summary: index list
      tags: []
      operationId: post-index_list
      description: Start indexing list of faces
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                list_id:
                  $ref: '#/components/schemas/list_id'
                index_id:
                  description: version of the index being created
                  type: string
                ef_construction:
                  description: index_time/index_accuracy ratio
                  type: int
              required:
                - list_id
                - index_id
                - ef_construction
            example:
              list_id: 1aaf9b4b-7865-4386-beaa-276822eb157e
              index_id: f9285806-371e-4c61-be00-0424029856e3
              ef_construction: 3200
      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:
                busy:
                  value:
                    error_code: 26101
                    desc: Indexer busy
                    detail: Indexer busy
                    link: >-
                      https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-26101
  /1/stop:
    post:
      summary: stop
      tags: []
      operationId: stop
      description: Stop current indexing task.
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      responses:
        '200':
          description: OK
        '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:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/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'
  /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'
  /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'
  /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: faces
                      error:
                        error_code: 0
                        desc: Success
                        detail: Success
                        link: >-
                          https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0
                      status: 1
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
    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.
  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
    index_id:
      description: index identifier
      type: string
      example: list-1645728697
    indexing:
      type: object
      properties:
        state:
          description: Indexing task in process.
          type: string
          enum:
            - indexing
        index_id:
          $ref: '#/components/schemas/index_id'
      required:
        - state
        - index_id
    new:
      type: object
      properties:
        state:
          description: Indexer instance has just started and has no index to process.
          type: string
          enum:
            - new
    success:
      type: object
      properties:
        state:
          description: Task successfully finished.
          type: string
          enum:
            - success
        index_id:
          $ref: '#/components/schemas/index_id'
        error:
          type: 'null'
      required:
        - state
        - index_id
        - error
    failure:
      type: object
      properties:
        state:
          description: Task failed.
          type: string
          enum:
            - error
        index_id:
          $ref: '#/components/schemas/index_id'
        error:
          allOf:
            - $ref: '#/components/schemas/error'
            - nullable: true
      required:
        - state
        - index_id
        - error
    state:
      oneOf:
        - $ref: '#/components/schemas/indexing'
        - $ref: '#/components/schemas/new'
        - $ref: '#/components/schemas/success'
        - $ref: '#/components/schemas/failure'
      discriminator:
        propertyName: state
    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
    list_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
        - example: 429b0e78-4616-426a-b57f-02baa72d638d
      description: luna list id.
    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
  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
