{
  "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"
    },
    {
      "name": "Services",
      "description": "Capabilities, SLAs, and engineering catalog"
    }
  ],
  "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"
              },
              "example": {
                "name": "Jane Doe",
                "email": "jane@enterprise.com",
                "service": "web",
                "message": "We need an enterprise Next.js and Node.js web application built with sub-20ms latency and high Core Web Vitals.",
                "_hp_trap": ""
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry accepted successfully. A senior engineer will review within 24 hours.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardSuccessResponse"
                },
                "example": {
                  "success": true,
                  "message": "Your inquiry has been received. A senior engineer will respond within 24 hours."
                }
              }
            }
          },
          "400": {
            "description": "Validation failure (e.g. invalid email syntax, unsupported service enum, or payload length violation).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "code": "VALIDATION_ERROR",
                  "error": "Please provide a valid email address.",
                  "message": "Input validation failed for field 'email'.",
                  "hint": "Check the ContactSubmissionRequest schema in /openapi.json for valid formats."
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (maximum 5 inquiries per 15-minute sliding window per IP address).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "code": "RATE_LIMIT_EXCEEDED",
                  "error": "Too many inquiries received from this IP address. Please try again in 15 minutes.",
                  "hint": "Wait for the 15-minute cooldown period or contact info@aevasoft.com directly."
                }
              }
            }
          },
          "500": {
            "description": "Internal server error during mail transport or downstream dispatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "code": "INTERNAL_ERROR",
                  "error": "An internal error occurred while processing your request. Please try again later.",
                  "hint": "If this persists, please email info@aevasoft.com directly."
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["System"],
        "summary": "Retrieve API health and uptime telemetry",
        "description": "Returns liveness and readiness status, process uptime in seconds, and ISO 8601 timestamp. Ideal for monitoring synthetic probes and agent pre-flight checks.",
        "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"
                },
                "example": {
                  "status": "healthy",
                  "uptimeSeconds": 86400,
                  "timestamp": "2026-09-18T12:00:00.000Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactSubmissionRequest": {
        "type": "object",
        "required": ["name", "email", "service", "message"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 100,
            "description": "Client full name or organization contact lead.",
            "example": "Jane Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "minLength": 5,
            "maxLength": 254,
            "description": "Valid corporate or personal email address for replies.",
            "example": "jane@enterprise.com"
          },
          "service": {
            "type": "string",
            "enum": ["web", "mobile", "seo", "erp", "custom"],
            "description": "Primary capability requested: 'web' (Web Applications), 'mobile' (iOS/Android), 'seo' (Technical SEO & AEO), 'erp' (Custom ERP), 'custom' (AI & Custom Software).",
            "example": "web"
          },
          "message": {
            "type": "string",
            "minLength": 10,
            "maxLength": 3000,
            "description": "Comprehensive project description, scope, timeline, or technical requirements.",
            "example": "We need an enterprise Next.js and Node.js web application built with sub-20ms latency and high Core Web Vitals."
          },
          "_hp_trap": {
            "type": "string",
            "description": "Transparent honeypot field. Must be left empty by legitimate humans and agents. If populated, request is classified as bot spam and silently dropped.",
            "default": ""
          }
        },
        "additionalProperties": false
      },
      "StandardSuccessResponse": {
        "type": "object",
        "required": ["success", "message"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Your inquiry has been received. A senior engineer will respond within 24 hours."
          }
        }
      },
      "HealthStatusResponse": {
        "type": "object",
        "required": ["status", "uptimeSeconds", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "example": "healthy"
          },
          "uptimeSeconds": {
            "type": "integer",
            "example": 86400
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-18T12:00:00.000Z"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code for agent branching.",
            "example": "VALIDATION_ERROR"
          },
          "error": {
            "type": "string",
            "description": "Short human-readable error title.",
            "example": "Please provide a valid email address."
          },
          "message": {
            "type": "string",
            "description": "Detailed diagnostic information without internal stack traces.",
            "example": "Input validation failed for field 'email'."
          },
          "hint": {
            "type": "string",
            "description": "Actionable instruction for the agent or client to resolve the error.",
            "example": "Check the ContactSubmissionRequest schema in /openapi.json for valid formats."
          }
        }
      }
    }
  }
}