{ "openapi": "3.0.0", "info": { "title": "Boat Designer Pro API", "description": "Professional marine engineering API for hull generation, resistance calculation, and propeller design. Used by naval architects and marine engineers worldwide.", "version": "1.0.0", "contact": { "name": "Naval Architecture AI", "url": "https://boat-designer-pro.pages.dev/", "email": "jason15994264083@gmail.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api-hull.boat-designer.pages.dev", "description": "Cloudflare Workers Production Server" }, { "url": "http://localhost:5000", "description": "Local Development Server" } ], "tags": [ { "name": "Hull Design", "description": "3D hull geometry generation and offset table calculation" }, { "name": "Resistance Calculation", "description": "Savitsky method for planing hull resistance prediction" }, { "name": "Propeller Design", "description": "B-Series propeller design with cavitation analysis" }, { "name": "Hydrostatics", "description": "Displacement, LCB, LCF, and hydrostatic properties" }, { "name": "Stability", "description": "GZ curve calculation and stability assessment" } ], "paths": { "/api/hull/generate": { "post": { "tags": ["Hull Design"], "summary": "Generate 3D Hull Geometry", "description": "Generate a complete 3D hull model with 20+ stations, including chine lines, deck lines, keel lines, and deadrise angle distribution. Returns offset table in JSON format.", "operationId": "generateHull", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["LOA", "Beam", "Draft", "Depth"], "properties": { "LOA": { "type": "number", "format": "float", "description": "Length Overall in meters", "example": 12.8, "minimum": 3, "maximum": 100 }, "Beam": { "type": "number", "format": "float", "description": "Maximum beam width in meters", "example": 3.2, "minimum": 1, "maximum": 20 }, "Draft": { "type": "number", "format": "float", "description": "Draft (depth below waterline) in meters", "example": 0.6, "minimum": 0.2, "maximum": 5 }, "Depth": { "type": "number", "format": "float", "description": "Molded depth in meters", "example": 1.8, "minimum": 0.5, "maximum": 10 }, "Deadrise": { "type": "number", "format": "float", "description": "Deadrise angle at midship in degrees (17-25 for planing hulls)", "example": 17, "minimum": 5, "maximum": 35 }, "LCG": { "type": "number", "format": "float", "description": "Longitudinal Center of Gravity as % of LOA from transom", "example": 40, "minimum": 30, "maximum": 50 } } } } } }, "responses": { "200": { "description": "Successful hull generation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "numStations": { "type": "integer", "example": 20 }, "stations": { "type": "array", "items": { "type": "object", "properties": { "st": { "type": "integer", "description": "Station number" }, "x": { "type": "number", "description": "X position from transom (m)" }, "keelZ": { "type": "number", "description": "Keel Z coordinate (m)" }, "chineY": { "type": "number", "description": "Chine half-breadth (m)" }, "chineZ": { "type": "number", "description": "Chine Z coordinate (m)" }, "deckY": { "type": "number", "description": "Deck half-breadth (m)" }, "deckZ": { "type": "number", "description": "Deck Z coordinate (m)" }, "deadrise": { "type": "number", "description": "Deadrise angle at station (degrees)" } } } }, "deadriseProfile": { "type": "object", "properties": { "transom": { "type": "number", "example": 11 }, "midship": { "type": "number", "example": 17 }, "bow": { "type": "number", "example": 35 } } } } } } } } } } }, "/api/hull/lcb": { "post": { "tags": ["Hydrostatics"], "summary": "Calculate Longitudinal Center of Buoyancy", "description": "Calculate LCB using Simpson's rule integration on the hull stations. Returns LCB position as distance from transom and as percentage of LOA.", "operationId": "calculateLCB", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["stations"], "properties": { "stations": { "type": "array", "items": { "type": "object" } }, "params": { "type": "object", "properties": { "LOA": { "type": "number" }, "Beam": { "type": "number" } } } } } } } }, "responses": { "200": { "description": "LCB calculation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "lcb": { "type": "number", "description": "LCB distance from transom (m)" }, "lcbPercent": { "type": "number", "description": "LCB as percentage of LOA" } } } } } } } } }, "/api/hull/optimize-lcg": { "post": { "tags": ["Hull Design"], "summary": "Optimize LCG Position", "description": "Find optimal LCG position for minimum resistance and best performance. Returns recommended LCG range based on hull type and speed.", "operationId": "optimizeLCG", "responses": { "200": { "description": "Optimized LCG recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "optimalLCG": { "type": "number", "description": "Optimal LCG percentage of LOA" }, "range": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } } } } } } } } } }, "/api/resistance/savitsky": { "post": { "tags": ["Resistance Calculation"], "summary": "Calculate Hull Resistance (Savitsky Method)", "description": "Calculate planing hull resistance using the Savitsky method with calibrated accuracy. Returns resistance curves, power requirements, and trim analysis.", "operationId": "calculateResistance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["LOA", "Beam", "Draft", "Depth", "Deadrise", "Displacement", "Speed"], "properties": { "LOA": { "type": "number", "description": "Length Overall (m)" }, "Beam": { "type": "number", "description": "Beam (m)" }, "Draft": { "type": "number", "description": "Draft (m)" }, "Depth": { "type": "number", "description": "Depth (m)" }, "Deadrise": { "type": "number", "description": "Deadrise angle at midship (degrees)" }, "Displacement": { "type": "number", "description": "Displacement (tonnes)" }, "Speed": { "type": "number", "description": "Target speed (knots)" }, "numScrews": { "type": "integer", "description": "Number of propellers", "default": 1 } } } } } }, "responses": { "200": { "description": "Resistance calculation results", "content": { "application/json": { "schema": { "type": "object", "properties": { "resistanceCurve": { "type": "array", "items": { "type": "object", "properties": { "speed": { "type": "number" }, "frictional": { "type": "number" }, "residual": { "type": "number" }, "air": { "type": "number" }, "total": { "type": "number" } } } }, "powerCurve": { "type": "array", "items": { "type": "object", "properties": { "speed": { "type": "number" }, "PE": { "type": "number" }, "PD": { "type": "number" }, "PB": { "type": "number" } } } } } } } } } } } }, "/api/propeller/b-series": { "post": { "tags": ["Propeller Design"], "summary": "Design B-Series Propeller", "description": "Design a B-Series propeller using Wageningen B-Series charts. Includes cavitation check, efficiency calculation, and gear ratio recommendation.", "operationId": "designPropeller", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["power", "speed", "rpm"], "properties": { "power": { "type": "number", "description": "Engine power (kW)" }, "speed": { "type": "number", "description": "Vessel speed (knots)" }, "rpm": { "type": "number", "description": "Propeller RPM" }, "gearRatio": { "type": "number", "description": "Gearbox reduction ratio" }, "bladeCount": { "type": "integer", "description": "Number of blades", "default": 4 } } } } } }, "responses": { "200": { "description": "Propeller design results", "content": { "application/json": { "schema": { "type": "object", "properties": { "diameter": { "type": "number", "description": "Propeller diameter (m)" }, "pitchRatio": { "type": "number", "description": "Pitch/Diameter ratio" }, "pitch": { "type": "number", "description": "Propeller pitch (m)" }, "EAR": { "type": "number", "description": "Expanded Area Ratio" }, "efficiency": { "type": "number", "description": "Open water efficiency" }, "cavitationCheck": { "type": "object", "properties": { "safe": { "type": "boolean" }, "sigmaMin": { "type": "number" }, "sigmaRequired": { "type": "number" } } } } } } } } } } }, "/api/health": { "get": { "tags": ["System"], "summary": "Health Check", "description": "Check API health and version status", "operationId": "healthCheck", "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } } }, "components": { "schemas": { "HullStation": { "type": "object", "properties": { "st": { "type": "integer" }, "x": { "type": "number" }, "keelZ": { "type": "number" }, "chineY": { "type": "number" }, "chineZ": { "type": "number" }, "deckY": { "type": "number" }, "deckZ": { "type": "number" }, "deadrise": { "type": "number" } } }, "ResistanceResult": { "type": "object", "properties": { "speed": { "type": "number" }, "frictional": { "type": "number" }, "residual": { "type": "number" }, "air": { "type": "number" }, "total": { "type": "number" } } }, "PowerResult": { "type": "object", "properties": { "speed": { "type": "number" }, "PE": { "type": "number", "description": "Effective Power" }, "PD": { "type": "number", "description": "Delivered Power" }, "PB": { "type": "number", "description": "Brake Power" } } } } }, "x-ai-integration": { "supportedAgents": ["Claude", "Perplexity", "Bing AI", "ChatGPT"], "usageExamples": [ { "agent": "Claude", "prompt": "Generate a 12.8 meter planing hull with 3.2m beam and 17 degree deadrise", "apiCall": "POST /api/hull/generate" }, { "agent": "Perplexity", "prompt": "Calculate resistance for a 25 knot patrol boat", "apiCall": "POST /api/resistance/savitsky" } ], "rateLimit": { "requests": 100, "period": "hour", "note": "Free tier limit for AI agents" } } }