{
  "openapi": "3.1.0",
  "info": {
    "title": "CecAI Studio™ Document Intelligence & Workflow API",
    "version": "2.4.1",
    "description": "Enterprise REST API for autonomous document extraction, verification, and contract drafting for Malaysian legal conveyancing and corporate filings.",
    "contact": {
      "name": "CEC Automation AI Solutions Engineering",
      "email": "info@cecaiautomation.my",
      "url": "https://cecaiautomation.my/"
    },
    "license": {
      "name": "Commercial SaaS License",
      "url": "https://cecaiautomation.my/#terms"
    }
  },
  "servers": [
    {
      "url": "https://cecaiautomation.my/api",
      "description": "Production Gateway (ASEAN - ap-southeast-1)"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Platform Health & Service Status",
        "operationId": "getHealthStatus",
        "responses": {
          "200": {
            "description": "All core processing pipelines operational",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/documents/parse": {
      "post": {
        "summary": "Extract Structured Entities from Legal & Conveyancing Documents",
        "description": "Parses scanned PDFs or images of Malaysian Land Titles (Geran Hakmilik), SSM Corporate Searches, MyKad, or Loan Facility Letters.",
        "operationId": "parseDocument",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Document file (PDF, TIFF, PNG, JPEG, up to 100MB)"
                  },
                  "document_type": {
                    "type": "string",
                    "enum": [
                      "geran_hakmilik",
                      "ssm_corporate_profile",
                      "mykad_identification",
                      "facility_letter",
                      "spa_agreement",
                      "auto_detect"
                    ],
                    "default": "auto_detect"
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "confidence_threshold": { "type": "number", "default": 0.90 },
                      "enable_human_review_flag": { "type": "boolean", "default": true }
                    }
                  }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured extraction payload with confidence scores and source coordinates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentExtractionResult"
                }
              }
            }
          },
          "400": { "description": "Invalid file format or corrupt document" },
          "401": { "description": "Unauthorized - Missing or invalid API key" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "operational" },
          "version": { "type": "string", "example": "2.4.1" },
          "region": { "type": "string", "example": "ap-southeast-1 (Kuala Lumpur / Singapore)" },
          "uptime": { "type": "string", "example": "99.98%" },
          "services": {
            "type": "object",
            "properties": {
              "docintelligence_ocr": { "type": "string", "example": "operational" },
              "flowrunner_orchestrator": { "type": "string", "example": "operational" },
              "docio_render_engine": { "type": "string", "example": "operational" },
              "billing_stripe": { "type": "string", "example": "operational" }
            }
          }
        }
      },
      "DocumentExtractionResult": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string", "example": "doc_9f81a7b8e21" },
          "document_type": { "type": "string", "example": "geran_hakmilik" },
          "overall_confidence": { "type": "number", "example": 0.994 },
          "entities": {
            "type": "object",
            "properties": {
              "title_number": { "type": "string", "example": "GRN 58219" },
              "lot_number": { "type": "string", "example": "Lot 4821" },
              "mukim": { "type": "string", "example": "Mukim Petaling" },
              "daerah": { "type": "string", "example": "Petaling" },
              "negeri": { "type": "string", "example": "Selangor" },
              "land_area": { "type": "string", "example": "782.5 sq metres" },
              "tenure": { "type": "string", "example": "Freehold (Pegangan Selamanya)" },
              "registered_proprietors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "example": "TAN SENG HOCK" },
                    "id_number": { "type": "string", "example": "820415-10-5893" },
                    "share": { "type": "string", "example": "1/1" }
                  }
                }
              },
              "encumbrances": {
                "type": "array",
                "items": { "type": "string", "example": "Charged to Malayan Banking Berhad (Presentation No. 04812/2021)" }
              },
              "restrictions_in_interest": {
                "type": "string",
                "example": "Tanah ini tidak boleh dipindahmilik, dipajak atau digadai melainkan dengan kebenaran Pihak Berkuasa Negeri."
              }
            }
          }
        }
      }
    }
  }
}