openapi: 3.1.0
info:
  title: Erayaha EIA Pre-Submission Audit API
  version: 2.0.0
  description: Programmatic pre-submission environmental clearance gap audit and statutory compliance verification for project proponents and environmental consultancies worldwide. All error responses conform to RFC 9457 Problem Details for HTTP APIs.
  contact:
    name: Erayaha Developer Desk
    email: developers@erayaha.ai
    url: https://eia-landing.pranay-442.workers.dev/developers
  license:
    name: Proprietary
    url: https://eia-landing.pranay-442.workers.dev/terms
  x-api-lifecycle:
    status: stable
    version: 2.0.0
    deprecationPolicy: https://eia-landing.pranay-442.workers.dev/versioning
    sunsetNoticeDays: 180

servers:
  - url: https://eia-landing.pranay-442.workers.dev
    description: Production Cloudflare Edge Server

paths:
  /api/v1/sandbox/keys:
    get:
      summary: Retrieve an instant zero-friction sandbox API key
      operationId: getSandboxKey
      description: Generates a zero-friction ephemeral sandbox API key for testing EIA audit pipelines.
      responses:
        '200':
          description: Sandbox API key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxKeyResponse'
        '429':
          $ref: '#/components/responses/ProblemDetails429'
        '500':
          $ref: '#/components/responses/ProblemDetails500'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      summary: Provision instant sandbox API key for AI agents
      operationId: createSandboxKey
      description: Generates a zero-friction ephemeral sandbox API key for testing EIA audit pipelines.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                agentName:
                  type: string
                  example: AgenticEiaAuditor
                  default: AgenticEiaClient
                environment:
                  type: string
                  enum: [sandbox, preview]
                  default: sandbox
      responses:
        '201':
          description: Sandbox API key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxKeyResponse'
        '400':
          $ref: '#/components/responses/ProblemDetails400'
        '429':
          $ref: '#/components/responses/ProblemDetails429'
        '500':
          $ref: '#/components/responses/ProblemDetails500'
        default:
          $ref: '#/components/responses/DefaultError'

  /api/v1/audits/pre-submission:
    post:
      summary: Execute simulated pre-submission proposal audit
      operationId: auditPreSubmission
      description: Scans proposal inputs against statutory criteria, cumulative spatial density buffers, terrain slope gradients, and setback distances.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditRequest'
      responses:
        '200':
          description: Statutory pre-submission gap audit dossier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResponse'
        '400':
          $ref: '#/components/responses/ProblemDetails400'
        '401':
          $ref: '#/components/responses/ProblemDetails401'
        '403':
          $ref: '#/components/responses/ProblemDetails403'
        '404':
          $ref: '#/components/responses/ProblemDetails404'
        '422':
          $ref: '#/components/responses/ProblemDetails422'
        '429':
          $ref: '#/components/responses/ProblemDetails429'
        '500':
          $ref: '#/components/responses/ProblemDetails500'
        default:
          $ref: '#/components/responses/DefaultError'

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer token or Sandbox key obtained from /api/v1/sandbox/keys

  schemas:
    SandboxKeyResponse:
      type: object
      required: [apiKey, agentName, environment, rateLimit, expiresAt, message]
      properties:
        apiKey:
          type: string
          example: eia_sb_7f8a9b2c3d4e5f
        agentName:
          type: string
          example: AgenticEiaClient
        environment:
          type: string
          example: sandbox
        rateLimit:
          type: string
          example: 120 req/min
        expiresAt:
          type: string
          format: date-time
        message:
          type: string

    AuditRequest:
      type: object
      required: [projectCategory, jurisdiction, latitude, longitude]
      properties:
        projectCategory:
          type: string
          enum: [energy, mining, infra, industry, commercial]
        jurisdiction:
          type: string
          enum: [US_NEPA, EU_DIRECTIVE, UK_REGULATIONS, AU_EPBC, CA_IAA, GCC_NCEC, IN_MOEFCC, GLOBAL_EQUATOR]
        projectScale:
          type: number
          example: 250
        scaleUnit:
          type: string
          enum: [hectares, acres, mw, m3_day, tpa]
          default: hectares
        latitude:
          type: number
          example: 36.1699
        longitude:
          type: number
          example: -115.1398
        nearestSensitiveHabitatKm:
          type: number
          example: 4.5
        maxTerrainSlopeDegrees:
          type: number
          example: 5.2

    AuditResponse:
      type: object
      required: [proposalStatus, riskScore, terminalVerdict, cumulativeSpatialAudit, terrainAudit, habitatSetbackAudit]
      properties:
        proposalStatus:
          type: string
          enum: [READY_FOR_SUBMISSION, ACTIONABLE_GAPS_IDENTIFIED, CRITICAL_MITIGATION_REQUIRED]
        riskScore:
          type: integer
          minimum: 0
          maximum: 100
          example: 25
        terminalVerdict:
          type: string
          example: READY_WITH_STANDARD_ANNEXURES
        cumulativeSpatialAudit:
          type: object
          required: [neighboringTenementsScreened, cumulativeDensityTriggered, summary]
          properties:
            neighboringTenementsScreened:
              type: integer
              example: 3
            cumulativeDensityTriggered:
              type: boolean
              example: false
            summary:
              type: string
              example: Regional multi-project spatial density within standard baseline envelope.
        terrainAudit:
          type: object
          required: [maxSlopeDegrees, hazardLevel]
          properties:
            maxSlopeDegrees:
              type: number
              example: 5.2
            hazardLevel:
              type: string
              example: STABLE_TOPOGRAPHY
        habitatSetbackAudit:
          type: object
          required: [nearestProtectedHabitatKm, setbackStatus]
          properties:
            nearestProtectedHabitatKm:
              type: number
              example: 4.5
            setbackStatus:
              type: string
              example: COMPLIANT_OUTSIDE_CRITICAL_BUFFER
        predictedAgencyInquiries:
          type: array
          items:
            type: string

    ProblemDetails:
      type: object
      required: [type, title, status, detail, code, hint, timestamp]
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        hint:
          type: string
        timestamp:
          type: string
          format: date-time

  responses:
    ProblemDetails400:
      description: Bad Request — RFC 9457 Structured Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails401:
      description: Unauthorized — missing or invalid API key
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails403:
      description: Forbidden — insufficient scope or privilege
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails404:
      description: Not Found — RFC 9457 Structured Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails422:
      description: Unprocessable Entity — semantic validation failure
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails429:
      description: Rate Limited — RFC 9457 Structured Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    ProblemDetails500:
      description: Internal Server Error — RFC 9457 Structured Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    DefaultError:
      description: Unexpected error — RFC 9457 Problem Details
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'