openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: API specification
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: verify
    description: Identity verification operations
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      description: Returns server health status
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
  /verify/face:
    post:
      operationId: verifyFace
      tags: [verify]
      summary: Compare face with national ID
      description: Compares a selfie with the face on a national ID using AI vision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FaceVerifyRequest"
      responses:
        "200":
          description: Verification result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FaceVerifyResult"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status
    FaceVerifyRequest:
      type: object
      properties:
        idImage:
          type: string
          description: Base64-encoded national ID image
        faceImage:
          type: string
          description: Base64-encoded selfie image
        country:
          type: string
          description: Country code for the ID
      required:
        - idImage
        - faceImage
        - country
    FaceVerifyResult:
      type: object
      properties:
        match:
          type: boolean
          description: Whether the faces match
        confidence:
          type: string
          enum: [high, medium, low]
        reason:
          type: string
          description: Explanation of the result
      required:
        - match
        - confidence
        - reason
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
        - error
