{
  "openapi": "3.1.0",
  "info": {
    "title": "Erayaha AI Document Reasoning & Contract Intelligence API",
    "version": "1.0.0",
    "description": "Deterministic structured reasoning compiler and automated contract vulnerability scanner for high-stakes enterprise agreements.",
    "contact": {
      "name": "Erayaha AI Developer Support",
      "url": "https://erayaha.ai/developers",
      "email": "developers@erayaha.ai"
    },
    "license": {
      "name": "Proprietary & Apache-2.0 Tools",
      "url": "https://erayaha.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://erayaha.ai",
      "description": "Production Edge Server"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getHealthStatus",
        "summary": "Check API and reasoning compiler health",
        "description": "Returns the operational health status and latency benchmarks of the Erayaha reasoning compiler.",
        "responses": {
          "200": {
            "description": "Service is healthy and operational",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatusResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ProblemResponse"
          }
        }
      }
    },
    "/api/v1/scan": {
      "post": {
        "operationId": "scanContractVulnerability",
        "summary": "Scan contract text for structural risks and clause liabilities",
        "description": "Compiles raw contract text into deterministic structural logic graphs to uncover circular obligations, indemnification loops, and missing caps.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique key to ensure idempotent execution for automated agent retries.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Contract content and target jurisdiction guidelines",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContractScanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful vulnerability and structural risk analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContractScanResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "422": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "429": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "500": {
            "$ref": "#/components/responses/ProblemResponse"
          }
        }
      }
    },
    "/api/v1/playbook/analyze": {
      "post": {
        "operationId": "analyzeClausePlaybook",
        "summary": "Analyze contract clauses against corporate fallback playbook",
        "description": "Evaluates contract clauses against corporate risk policies, identifying standard fallbacks and automated redline suggestions.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique key to ensure idempotent execution for automated agent retries.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Target clause text and organizational playbook guidelines",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybookAnalysisRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Playbook divergence scoring and recommended redlines",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaybookAnalysisResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "422": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "429": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "500": {
            "$ref": "#/components/responses/ProblemResponse"
          }
        }
      }
    },
    "/api/v1/roi/calculate": {
      "post": {
        "operationId": "calculateRoiSavings",
        "summary": "Calculate operational ROI and legal hours saved",
        "description": "Computes annualized legal savings, risk mitigation efficiency, and payback timeline based on contract review volume.",
        "requestBody": {
          "required": true,
          "description": "Annual contract review volume and legal operational parameters",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoiCalculationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comprehensive legal operational ROI metrics and projections",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoiCalculationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "422": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "429": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "500": {
            "$ref": "#/components/responses/ProblemResponse"
          }
        }
      }
    },
    "/api/v1/contracts/batch-scan": {
      "post": {
        "operationId": "batchScanContracts",
        "summary": "Batch scan multiple contract documents simultaneously",
        "description": "Executes high-throughput bulk verification and risk indexing across an array of enterprise contract documents in one request.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique key to ensure idempotent execution for automated agent retries.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Array of contract documents for batch analysis",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchScanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch processing results with per-contract risk breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchScanResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "422": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "429": {
            "$ref": "#/components/responses/ProblemResponse"
          },
          "500": {
            "$ref": "#/components/responses/ProblemResponse"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "ProblemResponse": {
        "description": "RFC 9457 structured error response",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "required": ["type", "title", "status", "detail", "code"],
        "properties": {
          "type": {
            "type": "string",
            "description": "URI reference identifying the problem type.",
            "example": "https://erayaha.ai/docs/errors#invalid-request"
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary of the problem.",
            "example": "Invalid Request Parameters"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code generated by the origin server.",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence.",
            "example": "The contract text parameter must be at least 50 characters."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code for programmatic handling.",
            "example": "INVALID_CONTRACT_LENGTH"
          },
          "hint": {
            "type": "string",
            "description": "Resolution hint for AI agents to self-correct requests.",
            "example": "Provide a complete contract body or clause excerpt."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-08-25T14:30:00Z"
          }
        }
      },
      "HealthStatusResponse": {
        "type": "object",
        "required": ["status", "version", "environment", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "example": "operational"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "environment": {
            "type": "string",
            "example": "production"
          },
          "latencyMs": {
            "type": "number",
            "example": 12.4
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContractScanRequest": {
        "type": "object",
        "required": ["contractText"],
        "properties": {
          "contractText": {
            "type": "string",
            "description": "Raw text or markdown of the contract to scan.",
            "minLength": 50
          },
          "documentType": {
            "type": "string",
            "enum": ["NDA", "MSA", "SOW", "DPA", "SLA", "Lease", "General"],
            "default": "General"
          },
          "jurisdiction": {
            "type": "string",
            "default": "US-Delaware",
            "example": "US-Delaware"
          },
          "strictness": {
            "type": "string",
            "enum": ["standard", "aggressive", "audit"],
            "default": "standard"
          }
        }
      },
      "ContractScanResponse": {
        "type": "object",
        "required": ["documentId", "riskScore", "status", "vulnerabilitiesCount", "vulnerabilities"],
        "properties": {
          "documentId": {
            "type": "string",
            "example": "doc_scan_98234ab"
          },
          "riskScore": {
            "type": "integer",
            "description": "Overall risk index from 0 (pristine) to 100 (critical liabilities).",
            "example": 42
          },
          "status": {
            "type": "string",
            "enum": ["SECURE", "ATTENTION", "CRITICAL"],
            "example": "ATTENTION"
          },
          "vulnerabilitiesCount": {
            "type": "integer",
            "example": 3
          },
          "vulnerabilities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "category", "severity", "clauseExcerpt", "explanation", "suggestedFix"],
              "properties": {
                "id": {
                  "type": "string",
                  "example": "vuln-01"
                },
                "category": {
                  "type": "string",
                  "example": "Unlimited Consequential Damages"
                },
                "severity": {
                  "type": "string",
                  "enum": ["LOW", "MEDIUM", "HIGH", "CRITICAL"],
                  "example": "HIGH"
                },
                "clauseExcerpt": {
                  "type": "string",
                  "example": "Neither party shall exclude indemnification for indirect or punitive damages..."
                },
                "explanation": {
                  "type": "string",
                  "example": "Uncapped indemnity creates unbounded liability exposure in data breach scenarios."
                },
                "suggestedFix": {
                  "type": "string",
                  "example": "Insert standard 12-month trailing fees aggregate liability cap."
                }
              }
            }
          }
        }
      },
      "PlaybookAnalysisRequest": {
        "type": "object",
        "required": ["clauseText", "clauseType"],
        "properties": {
          "clauseText": {
            "type": "string",
            "description": "Target clause text to compare against corporate policy."
          },
          "clauseType": {
            "type": "string",
            "enum": ["indemnity", "limitation_of_liability", "confidentiality", "governing_law", "termination", "ip_assignment"],
            "example": "indemnity"
          },
          "playbookStandard": {
            "type": "string",
            "default": "enterprise-standard-v2",
            "example": "enterprise-standard-v2"
          }
        }
      },
      "PlaybookAnalysisResponse": {
        "type": "object",
        "required": ["clauseType", "complianceStatus", "divergenceScore", "recommendedFallback"],
        "properties": {
          "clauseType": {
            "type": "string",
            "example": "indemnity"
          },
          "complianceStatus": {
            "type": "string",
            "enum": ["COMPLIANT", "ACCEPTABLE_DEVIATION", "NON_COMPLIANT"],
            "example": "ACCEPTABLE_DEVIATION"
          },
          "divergenceScore": {
            "type": "integer",
            "example": 28
          },
          "recommendedFallback": {
            "type": "string",
            "example": "Each party shall indemnify, defend, and hold harmless the other party solely against third-party claims arising from gross negligence..."
          },
          "redlineSummary": {
            "type": "string",
            "example": "Scoped indemnity solely to third-party claims and added gross negligence threshold."
          }
        }
      },
      "RoiCalculationRequest": {
        "type": "object",
        "required": ["annualContractVolume"],
        "properties": {
          "annualContractVolume": {
            "type": "integer",
            "description": "Total number of contracts reviewed per year.",
            "example": 450
          },
          "hourlyLegalRate": {
            "type": "number",
            "description": "Blended hourly internal/external legal counsel rate in USD.",
            "default": 350.0,
            "example": 350.0
          },
          "hoursPerContractManual": {
            "type": "number",
            "description": "Average hours spent manually redlining each contract.",
            "default": 4.5,
            "example": 4.5
          }
        }
      },
      "RoiCalculationResponse": {
        "type": "object",
        "required": ["annualSavingsUsd", "hoursSavedPerYear", "reviewTimeReductionPercent", "paybackMonths"],
        "properties": {
          "annualSavingsUsd": {
            "type": "number",
            "example": 567000.0
          },
          "hoursSavedPerYear": {
            "type": "number",
            "example": 1620.0
          },
          "reviewTimeReductionPercent": {
            "type": "number",
            "example": 80.0
          },
          "paybackMonths": {
            "type": "number",
            "example": 1.2
          }
        }
      },
      "BatchScanRequest": {
        "type": "object",
        "required": ["contracts"],
        "properties": {
          "contracts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "contractText"],
              "properties": {
                "id": {
                  "type": "string",
                  "example": "contract-001"
                },
                "documentType": {
                  "type": "string",
                  "example": "NDA"
                },
                "contractText": {
                  "type": "string",
                  "minLength": 50
                }
              }
            }
          }
        }
      },
      "BatchScanResponse": {
        "type": "object",
        "required": ["batchId", "totalScanned", "summary", "results"],
        "properties": {
          "batchId": {
            "type": "string",
            "example": "batch_9814abc"
          },
          "totalScanned": {
            "type": "integer",
            "example": 5
          },
          "summary": {
            "type": "object",
            "properties": {
              "secureCount": {
                "type": "integer",
                "example": 3
              },
              "attentionCount": {
                "type": "integer",
                "example": 1
              },
              "criticalCount": {
                "type": "integer",
                "example": 1
              }
            }
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContractScanResponse"
            }
          }
        }
      }
    }
  }
}