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'