openapi: 3.1.0
info:
  title: QR Code API
  version: "1.0.0"
  description: |
    Stateless API for generating PNG QR codes. API generation endpoints accept
    JSON or multipart/form-data, require an API key, and return the PNG directly
    in Base64 and data URI fields.
servers:
  - url: /
    description: API server base path
security:
  - ApiKeyHeader: []
  - BearerAuth: []
tags:
  - name: Health
  - name: QR Codes
paths:
  /healthz:
    get:
      tags: [Health]
      summary: Liveness probe
      operationId: health
      security: []
      responses:
        "200":
          description: The process is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
  /readyz:
    get:
      tags: [Health]
      summary: Readiness probe
      operationId: readiness
      security: []
      responses:
        "200":
          description: The process is ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
  /openapi.yaml:
    get:
      summary: OpenAPI specification
      operationId: openApiSpecification
      security: []
      responses:
        "200":
          description: OpenAPI 3.1 specification
          content:
            application/yaml:
              schema:
                type: string
  /api/v1/:
    get:
      tags: [QR Codes]
      summary: API index
      operationId: apiIndex
      responses:
        "200":
          description: API name, version, and endpoints
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIIndex"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/url:
    post:
      tags: [QR Codes]
      summary: Create a URL QR code
      operationId: createURLQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/URLRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/URLMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/vcard:
    post:
      tags: [QR Codes]
      summary: Create a vCard contact QR code
      operationId: createVCardQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VCardRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/VCardMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/wifi:
    post:
      tags: [QR Codes]
      summary: Create a Wi-Fi configuration QR code
      operationId: createWiFiQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WiFiRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/WiFiMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/calendar:
    post:
      tags: [QR Codes]
      summary: Create an iCalendar event QR code
      operationId: createCalendarQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CalendarRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CalendarMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/text:
    post:
      tags: [QR Codes]
      summary: Create a plain-text QR code
      operationId: createTextQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TextRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/TextMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/file:
    post:
      tags: [QR Codes]
      summary: Create a small-file data URI QR code
      operationId: createFileQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/FileMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/number:
    post:
      tags: [QR Codes]
      summary: Create a number QR code
      operationId: createNumberQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NumberRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/NumberMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/email:
    post:
      tags: [QR Codes]
      summary: Create an email compose QR code
      operationId: createEmailQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/EmailMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/sms:
    post:
      tags: [QR Codes]
      summary: Create an SMS QR code
      operationId: createSMSQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SMSRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SMSMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/qr/geolocation:
    post:
      tags: [QR Codes]
      summary: Create a geolocation QR code
      operationId: createGeolocationQR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GeolocationRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/GeolocationMultipartRequest"
      responses:
        "200":
          $ref: "#/components/responses/QRSuccess"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key with at least 16 characters.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Alternative API-key authentication using an Authorization Bearer header.
  parameters:
    Size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        minimum: 128
        maximum: 2048
        default: 256
      description: PNG width and height in pixels.
  schemas:
    StatusResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ok, ready]
    APIIndex:
      type: object
      required: [name, version, endpoints]
      properties:
        name:
          type: string
        version:
          type: string
          enum: [v1]
        endpoints:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
    LogoOptions:
      type: object
      properties:
        show_logo:
          type: boolean
          default: false
          description: Include a center logo. Custom PNG or configured fallback is used.
        logo_png_base64:
          type: string
          format: byte
          description: Base64-encoded PNG, accepted only for JSON requests.
    ImageOptions:
      type: object
      properties:
        size:
          type: integer
          minimum: 128
          maximum: 2048
          default: 256
        recovery:
          type: string
          enum: [low, medium, high, highest]
          default: medium
    URLRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [url]
          properties:
            url:
              type: string
              format: uri
              description: Absolute HTTP or HTTPS URL.
    URLMultipartRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
        size:
          type: integer
          minimum: 128
          maximum: 2048
          default: 256
        recovery:
          type: string
          enum: [low, medium, high, highest]
          default: medium
        show_logo:
          type: boolean
          default: false
        logo:
          type: string
          format: binary
          description: Optional PNG upload. logo_file is also accepted.
    VCardRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          properties:
            first_name: {type: string}
            last_name: {type: string}
            organization: {type: string}
            title: {type: string}
            phone: {type: string}
            email: {type: string, format: email}
            website: {type: string, format: uri}
            address: {type: string}
          anyOf:
            - required: [first_name]
            - required: [last_name]
    VCardMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/VCardRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    WiFiRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [ssid]
          properties:
            ssid: {type: string, minLength: 1}
            password: {type: string}
            security:
              type: string
              enum: [WPA, WEP, NOPASS]
              default: WPA
            hidden:
              type: boolean
              default: false
    WiFiMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/WiFiRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    CalendarRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [title, start]
          properties:
            title: {type: string, minLength: 1}
            description: {type: string}
            location: {type: string}
            start:
              type: string
              description: RFC 3339 timestamp or YYYY-MM-DD for all-day events.
            end:
              type: string
              description: RFC 3339 timestamp or YYYY-MM-DD for all-day events.
            timezone: {type: string}
            all_day:
              type: boolean
              default: false
    CalendarMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/CalendarRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    TextRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [text]
          properties:
            text: {type: string, minLength: 1}
    TextMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/TextRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    FileRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [filename, base64_content]
          properties:
            filename: {type: string, minLength: 1}
            mime_type:
              type: string
              default: application/octet-stream
            base64_content:
              type: string
              format: byte
              description: Decoded file content limit is 1024 bytes.
    FileMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/FileRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    NumberRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [number]
          properties:
            number:
              type: string
              description: Number or telephone-style digits and formatting.
    NumberMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/NumberRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    EmailRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [email]
          properties:
            email: {type: string, format: email}
            subject: {type: string}
            body: {type: string}
    EmailMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/EmailRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    SMSRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [phone]
          properties:
            phone: {type: string, minLength: 1}
            body: {type: string}
    SMSMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/SMSRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    GeolocationRequest:
      allOf:
        - $ref: "#/components/schemas/ImageOptions"
        - $ref: "#/components/schemas/LogoOptions"
        - type: object
          required: [latitude, longitude]
          properties:
            latitude:
              type: number
              format: double
              minimum: -90
              maximum: 90
            longitude:
              type: number
              format: double
              minimum: -180
              maximum: 180
            label: {type: string}
    GeolocationMultipartRequest:
      allOf:
        - $ref: "#/components/schemas/GeolocationRequest"
        - type: object
          properties:
            logo:
              type: string
              format: binary
    QRCode:
      type: object
      required: [type, format, size, recovery, logo_included, png_base64, data_uri]
      properties:
        type:
          type: string
          enum: [url, vcard, wifi, calendar, text, file, number, email, sms, geolocation]
        format:
          type: string
          enum: [png]
        size:
          type: integer
          minimum: 128
          maximum: 2048
        recovery:
          type: string
          enum: [low, medium, high, highest]
        logo_included:
          type: boolean
        logo_source:
          type: string
          enum: [custom, fallback]
          description: Included only when logo_included is true.
        png_base64:
          type: string
          contentEncoding: base64
        data_uri:
          type: string
          pattern: '^data:image/png;base64,'
    QRSuccessResponse:
      type: object
      required: [qr_code]
      properties:
        qr_code:
          $ref: "#/components/schemas/QRCode"
  responses:
    QRSuccess:
      description: QR code generated successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/QRSuccessResponse"
    BadRequest:
      description: Invalid JSON, unsupported field, invalid payload, or invalid logo
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
