{
  "openapi": "3.0.3",
  "info": {
    "title": "Idiomatic Document Merge & Verification API",
    "description": "API for automated spreadsheet mail merge, Remote Online Notarization (RON) PDF verification, cryptographic SHA-256 document hashing, student report card certification, and multi-party e-signatures.",
    "version": "1.0.0",
    "contact": {
      "name": "Idiomatic Support Team",
      "url": "https://certverify.app",
      "email": "dcreus@idiomatic.net"
    }
  },
  "servers": [
    {
      "url": "https://certverify.app",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Check API Health Status",
        "description": "Returns status ok and server timestamp.",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "timestamp": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/verify-ron": {
      "post": {
        "summary": "Verify PDF Document Authenticity & Cryptographic Integrity",
        "description": "Analyzes a uploaded PDF buffer or base64 stream to verify SHA-256 hashes, notary stamps, and tamper detection.",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "pdfFile": {
                    "type": "string",
                    "format": "binary",
                    "description": "PDF document file to verify"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pdfBytesBase64": { "type": "string", "description": "Base64 encoded PDF string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "isValid": { "type": "boolean" },
                    "status": { "type": "string", "example": "AUTHENTIC_NOTARIZED" },
                    "errorMessage": { "type": "string" },
                    "baseDocument": {
                      "type": "object",
                      "properties": {
                        "hash": { "type": "string" },
                        "isVerified": { "type": "boolean" },
                        "timestamp": { "type": "string" }
                      }
                    },
                    "tamperedAfterNotary": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/verify-batch": {
      "post": {
        "summary": "Verify Batch of PDF Documents",
        "description": "Verify up to 50 PDF files simultaneously for bulk academic or corporate record auditing.",
        "responses": {
          "200": {
            "description": "Batch verification summary and results array"
          }
        }
      }
    },
    "/api/send-batch-mail-merge": {
      "post": {
        "summary": "Dispatch Batch Document Mail Merge via SMTP",
        "description": "Dispatches personalized PDF report cards or certificates to multiple recipients via custom or system SMTP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "recipientName": { "type": "string" },
                        "recipientEmail": { "type": "string" },
                        "subject": { "type": "string" },
                        "pdfBase64": { "type": "string" }
                      },
                      "required": ["recipientEmail"]
                    }
                  }
                },
                "required": ["items"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Batch dispatch report" }
        }
      }
    },
    "/api/v1/signatures": {
      "post": {
        "summary": "Create Automated Signature Request",
        "description": "Creates an e-signature request with custom signers, webhook callbacks, and PDF attachments.",
        "responses": {
          "201": { "description": "Signature request successfully created" }
        }
      }
    },
    "/api/gemini/detect-fields": {
      "post": {
        "summary": "AI Field & Signature Block Auto-Detection",
        "description": "Uses Gemini AI vision to detect signature boxes, date lines, and notary stamps on document pages.",
        "responses": {
          "200": { "description": "Detected signature fields" }
        }
      }
    }
  }
}