{
  "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 Developer Support",
      "url": "https://erayaha.ai/developers",
      "email": "developers@erayaha.ai"
    },
    "license": {
      "name": "Proprietary & Apache-2.0 Tools",
      "url": "https://erayaha.ai/terms"
    },
    "x-versioning-policy": {
      "currentVersion": "v1",
      "sunsetDate": "2028-12-31T23:59:59Z",
      "deprecationHeader": "Deprecation",
      "sunsetHeader": "Sunset",
      "policyUrl": "https://erayaha.ai/docs/versioning"
    }
  },
  "servers": [
    {
      "url": "https://erayaha.ai",
      "description": "Production Edge Server"
    }
  ],
  "security": [
    {
      "OAuth2": [
        "contracts:read",
        "contracts:scan",
        "playbooks:analyze",
        "roi:calculate"
      ]
    },
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "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.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy and operational",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatusResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    },
    "/api/v1/sandbox/keys": {
      "post": {
        "operationId": "generateSandboxApiKey",
        "summary": "Instantly generate free sandbox API key",
        "description": "Generates a zero-friction self-serve sandbox API key for autonomous AI agents and automated testing with immediate activation.",
        "security": [],
        "responses": {
          "200": {
            "description": "Sandbox API key generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxKeyResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedProblem"
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    },
    "/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.",
        "security": [
          { "OAuth2": ["contracts:scan"] },
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "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/BadRequestProblem"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedProblem"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableProblem"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedProblem"
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    },
    "/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.",
        "security": [
          { "OAuth2": ["playbooks:analyze"] },
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "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/BadRequestProblem"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedProblem"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableProblem"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedProblem"
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    },
    "/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.",
        "security": [
          { "OAuth2": ["roi:calculate"] },
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "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/BadRequestProblem"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedProblem"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableProblem"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedProblem"
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    },
    "/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.",
        "security": [
          { "OAuth2": ["contracts:scan"] },
          { "ApiKeyAuth": [] },
          { "BearerAuth": [] }
        ],
        "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/BadRequestProblem"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedProblem"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableProblem"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedProblem"
          },
          "500": {
            "$ref": "#/components/responses/InternalProblem"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 authorization with scoped machine-readable permissions for AI agents.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://erayaha.ai/oauth/token",
            "scopes": {
              "contracts:read": "Read-only access to contract analysis and compliance benchmarks",
              "contracts:scan": "Execute structured risk scanning and liability graph compilation",
              "contracts:write": "Create and update contract review projects and redlines",
              "playbooks:read": "Read corporate clause fallbacks and risk policies",
              "playbooks:analyze": "Compare contracts against corporate risk playbooks",
              "roi:calculate": "Compute operational ROI and legal hours saved"
            }
          },
          "authorizationCode": {
            "authorizationUrl": "https://erayaha.ai/oauth/authorize",
            "tokenUrl": "https://erayaha.ai/oauth/token",
            "scopes": {
              "contracts:read": "Read-only access to contract analysis and compliance benchmarks",
              "contracts:scan": "Execute structured risk scanning and liability graph compilation",
              "contracts:write": "Create and update contract review projects and redlines",
              "playbooks:read": "Read corporate clause fallbacks and risk policies",
              "playbooks:analyze": "Compare contracts against corporate risk playbooks",
              "roi:calculate": "Compute operational ROI and legal hours saved"
            }
          }
        }
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API Key authentication. Free sandbox keys can be provisioned at POST /api/v1/sandbox/keys."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JSON Web Token (JWT) issued via OAuth 2.0 token endpoint."
      }
    },
    "responses": {
      "BadRequestProblem": {
        "description": "Invalid parameters or malformed request payload (RFC 9457)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "UnauthorizedProblem": {
        "description": "Missing, invalid, or expired authentication token (RFC 9457)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFoundProblem": {
        "description": "Target resource or API endpoint not found (RFC 9457)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "UnprocessableProblem": {
        "description": "Semantic validation error on document input (RFC 9457)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "RateLimitedProblem": {
        "description": "Too many requests - rate limit exceeded (RFC 9457)",
        "headers": {
          "Retry-After": {
            "schema": { "type": "integer" },
            "description": "Seconds to wait before retrying request"
          },
          "RateLimit-Limit": {
            "schema": { "type": "integer" },
            "description": "Quota limit per window"
          },
          "RateLimit-Remaining": {
            "schema": { "type": "integer" },
            "description": "Remaining quota in window"
          },
          "RateLimit-Reset": {
            "schema": { "type": "integer" },
            "description": "Seconds until window resets"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalProblem": {
        "description": "Internal compiler or reasoning engine error (RFC 9457)",
        "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",
            "example": "2026-08-25T14:30:00Z"
          }
        }
      },
      "SandboxKeyResponse": {
        "type": "object",
        "required": ["apiKey", "tier", "rateLimitPerMinute", "scopes", "docsUrl"],
        "properties": {
          "apiKey": {
            "type": "string",
            "example": "era_sandbox_live_89f3a12bcd45e67"
          },
          "tier": {
            "type": "string",
            "example": "free_community"
          },
          "rateLimitPerMinute": {
            "type": "integer",
            "example": 120
          },
          "scopes": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["contracts:scan", "playbooks:analyze", "roi:calculate"]
          },
          "docsUrl": {
            "type": "string",
            "example": "https://erayaha.ai/docs"
          }
        }
      },
      "ContractScanRequest": {
        "type": "object",
        "required": ["contractText"],
        "properties": {
          "contractText": {
            "type": "string",
            "description": "Full contract or clause text to scan (minimum 50 characters).",
            "example": "In the event of a breach, Provider shall indemnify Customer for all consequential damages without limitation."
          },
          "documentType": {
            "type": "string",
            "enum": ["NDA", "MSA", "SOW", "DPA", "SLA", "Lease", "General"],
            "default": "General",
            "example": "MSA"
          },
          "jurisdiction": {
            "type": "string",
            "default": "US-CA",
            "example": "US-DE"
          }
        }
      },
      "ContractScanResponse": {
        "type": "object",
        "required": ["documentId", "riskScore", "status", "vulnerabilitiesCount", "vulnerabilities"],
        "properties": {
          "documentId": {
            "type": "string",
            "example": "doc_scan_8pnvv92"
          },
          "riskScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 38
          },
          "status": {
            "type": "string",
            "enum": ["SECURE", "ATTENTION", "CRITICAL"],
            "example": "ATTENTION"
          },
          "vulnerabilitiesCount": {
            "type": "integer",
            "example": 1
          },
          "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": "Provider shall indemnify Customer for all consequential damages without limitation."
                },
                "explanation": {
                  "type": "string",
                  "example": "Uncapped indemnity creates unbounded liability exposure in 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": "Clause text to analyze against standard positions.",
            "example": "Neither party shall disclose confidential information for 1 year following termination."
          },
          "clauseType": {
            "type": "string",
            "enum": ["indemnity", "limitation_of_liability", "confidentiality", "governing_law", "termination", "ip_assignment"],
            "example": "confidentiality"
          }
        }
      },
      "PlaybookAnalysisResponse": {
        "type": "object",
        "required": ["matchScore", "divergenceLevel", "standardPosition", "recommendedRedline"],
        "properties": {
          "matchScore": {
            "type": "integer",
            "example": 65
          },
          "divergenceLevel": {
            "type": "string",
            "enum": ["ACCEPTABLE", "MODERATE_DIVERGENCE", "CRITICAL_DEVIATION"],
            "example": "MODERATE_DIVERGENCE"
          },
          "standardPosition": {
            "type": "string",
            "example": "5-year confidentiality obligation from disclosure date."
          },
          "recommendedRedline": {
            "type": "string",
            "example": "Neither party shall disclose confidential information for 5 years following disclosure."
          }
        }
      },
      "RoiCalculationRequest": {
        "type": "object",
        "required": ["annualContractVolume"],
        "properties": {
          "annualContractVolume": {
            "type": "integer",
            "example": 500
          },
          "hourlyLegalRate": {
            "type": "number",
            "default": 350.0,
            "example": 350.0
          },
          "hoursPerContractManual": {
            "type": "number",
            "default": 4.5,
            "example": 4.5
          }
        }
      },
      "RoiCalculationResponse": {
        "type": "object",
        "required": ["annualNetSavings", "hoursSavedPerYear", "reviewTimeReductionPercent", "paybackMonths"],
        "properties": {
          "annualNetSavings": {
            "type": "number",
            "example": 542000.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"
            }
          }
        }
      }
    }
  }
}