openapi: 3.0.1
info:
  title: QRCodeCrafter API
  version: "1.0.0"
  description: Generate branded QR codes in multiple formats via the QR Code Crafter service.
  termsOfService: https://qrcodecrafter.com/terms
  contact:
    name: QR Code Crafter Agent Support
    email: support@qrcodecrafter.com
servers:
  - url: https://qrcodecrafter.com
    description: Production
paths:
  /.netlify/functions/generate-qr:
    get:
      summary: Download a QR code asset via Netlify Function
      operationId: downloadQr
      security:
        - AgentApiKey: []
        - {}
      parameters:
        - name: value
          in: query
          required: true
          description: Text, URL, or payload encoded in the QR code
          schema:
            type: string
        - name: format
          in: query
          description: Output format for the QR code asset
          schema:
            type: string
            enum: [svg, png, jpg, webp, pdf, eps]
            default: png
        - name: size
          in: query
          description: Width and height of the generated asset in pixels
          schema:
            type: integer
            minimum: 256
            maximum: 4096
        - name: bgColor
          in: query
          description: Background color in hex format (e.g. #FFFFFF)
          schema:
            type: string
        - name: fgColor
          in: query
          description: Foreground color in hex format (e.g. #000000)
          schema:
            type: string
        - name: errorCorrectionLevel
          in: query
          description: Error correction level for QR encoding
          schema:
            type: string
            enum: [L, M, Q, H]
        - name: logo
          in: query
          description: Optional base64 data URL for an embedded logo
          schema:
            type: string
      responses:
        '200':
          description: Generated QR code asset served as binary content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key when key enforcement is enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests, slow down before retrying
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Generate a QR code asset via Netlify Function
      operationId: generateQr
      security:
        - AgentApiKey: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateQrRequest'
      responses:
        '200':
          description: Generated QR code asset encoded as base64
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateQrResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key when key enforcement is enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests, slow down before retrying
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/send-feedback:
    post:
      summary: Send user feedback
      operationId: sendFeedback
      security:
        - AgentApiKey: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                message:
                  type: string
      responses:
        '200':
          description: Feedback logged
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key when key enforcement is enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GenerateQrRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: Data encoded in the QR code
          maxLength: 2048
        format:
          type: string
          description: Output format for the QR code asset
          enum: [svg, png, jpg, webp, pdf, eps]
          default: png
        size:
          type: integer
          minimum: 256
          maximum: 4096
          default: 1024
          description: Pixel width/height of the generated asset
        margin:
          type: integer
          minimum: 0
          maximum: 16
          default: 4
          description: Quiet-zone margin around the QR code modules
        fgColor:
          type: string
          pattern: '^#?[0-9a-fA-F]{6}$'
          description: Hex foreground color (default black)
        bgColor:
          type: string
          pattern: '^#?[0-9a-fA-F]{6}$'
          description: Hex background color (default white)
        errorCorrectionLevel:
          type: string
          enum: [L, M, Q, H]
          default: H
          description: QR error correction level
        logo:
          type: string
          nullable: true
          maxLength: 1500000
          pattern: '^data:image\/(png|jpe?g|webp|svg\+xml);base64,.+'
          description: >-
            Optional base64 data URL for a logo (PNG, JPG, WEBP, or SVG) to composite
            at the center. Files larger than 1MB are rejected.
    GenerateQrResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded asset bytes
        contentType:
          type: string
          example: image/png
        extension:
          type: string
          example: png
        suggestedFilename:
          type: string
          example: qrcode-example
    Error:
      type: object
      properties:
        success:
          type: boolean
          default: false
        error:
          type: string
  securitySchemes:
    AgentApiKey:
      type: apiKey
      in: header
      name: X-Agent-Api-Key
      description: Optional API key used when integrations need scoped or rate-limited access.
