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'