openapi: 3.1.0
info:
  title: AevaSoft Public API
  version: 1.0.0
  description: >
    Programmatic interface and machine-readable endpoints for AevaSoft Technologies —
    an elite software engineering and digital product studio. Enables AI agents and developers
    to submit project inquiries, verify uptime, retrieve service capabilities, and estimate timelines.
  contact:
    name: AevaSoft Engineering Team
    email: info@aevasoft.com
    url: https://aevasoft.com/#contact
  license:
    name: Proprietary / Commercial
    url: https://aevasoft.com/privacy

servers:
  - url: https://aevasoft.com
    description: Production Edge API Gateway
  - url: http://localhost:5000
    description: Local Development / Sandbox Environment

tags:
  - name: Inquiries
    description: Endpoints for submitting client inquiries and consulting requests
  - name: System
    description: Health checks, liveness probes, and uptime telemetry

paths:
  /api/contact:
    post:
      tags:
        - Inquiries
      summary: Submit a client inquiry or consultation request
      description: >
        Accepts project parameters from prospective clients or autonomous agents,
        validates the payload against OWASP input boundaries, and dispatches parallel
        notifications to senior engineering architects and the sender.
      operationId: submitInquiry
      x-openai-isConsequential: false
      requestBody:
        required: true
        description: Client contact details, requested engineering capability, and project brief.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSubmissionRequest'
      responses:
        '200':
          description: Inquiry accepted successfully. A senior engineer will review within 24 hours.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardSuccessResponse'
        '400':
          description: Validation failure (invalid syntax, unsupported service enum, length violation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded (maximum 5 inquiries per 15-minute sliding window per IP).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/health:
    get:
      tags:
        - System
      summary: Retrieve API health and uptime telemetry
      description: Returns liveness status, uptime in seconds, and timestamp.
      operationId: getHealthStatus
      x-openai-isConsequential: false
      responses:
        '200':
          description: System is healthy and ready to process traffic.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatusResponse'

components:
  schemas:
    ContactSubmissionRequest:
      type: object
      required:
        - name
        - email
        - service
        - message
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email
          minLength: 5
          maxLength: 254
        service:
          type: string
          enum: [web, mobile, seo, erp, custom]
        message:
          type: string
          minLength: 10
          maxLength: 3000
        _hp_trap:
          type: string
          default: ""
      additionalProperties: false

    StandardSuccessResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string

    HealthStatusResponse:
      type: object
      required:
        - status
        - uptimeSeconds
        - timestamp
      properties:
        status:
          type: string
        uptimeSeconds:
          type: integer
        timestamp:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
        code:
          type: string
        error:
          type: string
        message:
          type: string
        hint:
          type: string