OpenAPI Documentation

You can find the OpenAPI specification with requests examples for the Licenses service in the html document.

openapi: 3.0.0
info:
  version: 'v.0.10.10'
  title: 'Luna-Licenses'
  description: |

          VisionLabs Luna Licenses.

          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".

servers:
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/visionlabs/Luna3API/v.0.10.10

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

    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.

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

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

    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: Page number.

    accept_docs_handler:
      in: header
      name: Accept
      schema:
        $ref: '#/components/schemas/accept_docs_handler'
      description: Acceptable type of receiving data.

    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

    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.

    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.

    get_license_target:
      in: query
      name: targets
      schema:
        type: string
        default: "expiration_time,faces_limit,liveness,iso,index,people_counter,body_attributes,streams_limit,lambdas"
      description: |
        Comma-separated list of face target fields. Available targets: `expiration_time`, `faces_limit`, `liveness`, `iso`, `index`, `people_counter`, `body_attributes`, `streams_limit`, `lambdas`
      example: "expiration_time,faces_limit"
  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.
        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"

    int_version:
      type: integer
      minimum: 0

    consumed_executions:
      type: integer
      minimum: 0
      description: Consumed executions number.

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

    version:
      type: object
      properties:
        api:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: API version of service.
        major:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: Major version of service.
        minor:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: Minor version of service.
        patch:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: Patch version of service.
      required: [api, major, minor, patch]

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

    version_response:
      type: object
      properties:
        Version:
          allOf:
          - $ref: '#/components/schemas/version'
          - description: Service version info.
      required: [Version]

    license_period:
      type: object
      properties:
        is_available:
          type: boolean
          description: Whether the license is valid.
          example: True
        value:
          oneOf:
            - type: string
              format: date-time
              example: "2021-08-11T09:11:41.674Z"
            - type: string
              enum: [ PERPETUAL ]
          description: License expiration time.

    license_feature:
      type: object
      properties:
        is_available:
          type: boolean
          description: Whether the license feature is available.
          example: True
        value:
          type: integer
          minimum: 0
          nullable: True
          description: License feature current value.

    license:
      type: object
      description: Current license data.
      properties:
        expiration_time:
          allOf:
            - $ref: '#/components/schemas/license_period'
            - description: Expiration time of your license.
        faces_limit:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: |
                Information about allowed faces database size:

                - feature availability

                - maximum number of faces with attached attributes
          example:
            is_available: True
            value: 1000
        liveness:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about liveness feature availability.
          example:
            is_available: True
            value: 1
        liveness_balance:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about allowed liveness executions.
          example:
            is_available: True
            value: 1000
        streams_limit:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: maximum number of streams.
          example:
            is_available: True
            value: 10
        iso:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about ISO feature availability.
          example:
            is_available: True
            value: 1
        index:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about matching by index feature availability.
          example:
            is_available: True
            value: 1
        body_attributes:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about body attributes estimation feature availability.
          example:
            is_available: True
            value: 1
        people_counter:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about people counter feature availability.
          example:
            is_available: True
            value: 1
        lambdas:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about lambdas feature availability.
          example:
            is_available: True
            value: 1
        deepfake:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: Information about deepfake feature availability.
          example:
            is_available: True
            value: 1


    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:
            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: license
            error:
              error_code: 38001
              desc: Health check error
              detail: License error
              link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-38001"
            status: 0
          - component: luna_faces
            error:
              error_code: 0
              desc: Success
              detail: Success
              link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0"
            status: 1

    feature_execution_count:
      type: object
      properties:
        execution_count:
          type: integer
          minimum: 1
          description: Execution count to consume for the feature.
      required: [execution_count]

    consume_executions:
      type: object
      properties:
        liveness:
          allOf:
          - $ref: '#/components/schemas/feature_execution_count'
          description: |
            `Liveness` feature.
      required: [liveness]
      example:
        liveness:
          execution_count: 200

    executions_response:
      type: object
      properties:
        liveness:
          type: object
          properties:
            result:
              allOf:
              - $ref: '#/components/schemas/Error'
              description: |
                `Liveness` executions consumption result.
            consumed_executions:
              $ref: '#/components/schemas/consumed_executions'
          required: [result, consumed_executions]
          description: |
            `Liveness` execution consumption result and consumed executions number.
      required: [liveness]

    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:
          description: list of imported plugins
          type: array
          items:
            $ref: '#/components/schemas/plugin_status'
      required: [plugins]
      example:
        plugins:
          - name: foo
            running: 1
  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'

    internal_server_license_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'
          examples:
            failed_to_check_feature:
              value:
                error_code: 33001
                desc: License problem
                detail: 'Failed to check license feature PlatformFacesLimit: Internal'
                link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33001"
            failed_to_get_feature_value:
              value:
                error_code: 33002
                desc: License problem
                detail: 'Failed to get value of license feature PlatformFacesLimit: Internal'
                link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33002"
            no_value_for_required_feature:
              value:
                error_code: 33003
                desc: License problem
                detail: 'No value found for required license feature PlatformFacesLimit: Internal'
                link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33003"

    forbidden_error:
      description: Forbidden, user did not set header Luna-Account-Id.
      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'
          example:
            error_code: 11036
            desc: Forbidden
            detail: Luna-Account-Id header is required for requests that change the state of system
            link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-11036"
    forbidden_events_error:
      description: Forbidden, luna-events support is disabled on server.
      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'
          example:
            error_code: 11040
            desc: Forbidden
            detail: Luna Events service is disabled
            link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-11040"
    forbidden_tasks_error:
      description: forbidden, luna-tasks support is disabled on server
      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'
          example:
            error_code: 11039
            desc: Forbidden
            detail: Luna Tasks service is disabled
            link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-11039"

    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"
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_response'
        500:
          $ref: '#/components/responses/internal_server_error'
  /1/docs:
    get:
      tags:
      - documents

      summary: get docs
      description: Get service documentation.
      operationId: getDocs

      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
            text/html:
              schema:
                type: string
        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/license:
    get:
      tags:
      - license

      summary: get license
      description: |
        Get license data:
        - license expiration date (`expiration_time`)
        - maximum number of faces with linked descriptor or basic attributes (`faces_limit`)
        - liveness feature availability (`liveness`)
        - current number of Liveness transactions (`liveness_balance`)
        - maximum number of streams created by the LUNA Streams service (`streams_limit`)
        - image check according to ISO/IEC 19794-5 standard availability (`iso`)
        - using the Index Matcher service in the LUNA Index Module availability (`index`)
        - body attributes estimation availability (`body_attributes`)
        - people counter estimation availability (`people_counter`)
        - lambdas availability (`lambdas`)

      operationId: getLicense

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/get_license_target'
      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/license'
        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: 33006
                    desc: Bad input data
                    detail: "'INDEX' is not valid target to get license features. Valid target should be one of {'body_attributes', 'faces_limit', 'streams_limit', 'liveness', 'people_counter', 'index', 'iso', 'expiration_time'}"
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33006"
        500:
          $ref: '#/components/responses/internal_server_license_error'
  /1/license/executions:
    post:
      tags:
      - executions consumption

      summary: executions consumption
      description: Consume executions for the given features.
      operationId: consumeExecutions

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/consume_executions'
      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/executions_response'
              examples:
                success:
                  value:
                    liveness:
                      result:
                        error_code: 0
                        detail: Success
                        desc: Success
                        link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-0"
                      consumed_executions: 1
                not_found:
                  value:
                    liveness:
                      result:
                        error_code: 33004
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: NotFound"
                        link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33004"
                      consumed_executions: 0
                insufficient:
                  value:
                    liveness:
                      result:
                        error_code: 33005
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: license expired"
                        link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33005"
                      consumed_executions: 5
                expired:
                  value:
                    liveness:
                      result:
                        error_code: 33005
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: LicenseExpired"
                        link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-33005"
                      consumed_executions: 0
        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)'''
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022"
        500:
          $ref: '#/components/responses/internal_server_license_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'
        - $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.
                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'
  /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/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:
                $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'