{"openapi":"3.1.0","info":{"title":"AI Recommendation Readiness Assessment API","version":"2.0.0","description":"Canonical REST door for the AI Recommendation Readiness assessment engine by The Black Friday Agency. Given structured inputs (business size, data availability/maturity, technical stack/infrastructure, and goals), it returns a readiness score, tier, gap analysis, priority actions, and a phased implementation roadmap. Deterministic and read-only: it performs no consequential actions and makes no guarantee of ranking or recommendation.","contact":{"name":"The Black Friday Agency","url":"https://canairecommendmybusiness.com"}},"servers":[{"url":"https://canairecommendmybusiness.com","description":"Production"}],"paths":{"/api/v1/assess-ai-recommendation-readiness":{"get":{"summary":"Describe this assessment endpoint","operationId":"describeAssessment","responses":{"200":{"description":"A self-describing summary of the REST door.","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Assess AI recommendation readiness","operationId":"assess_ai_recommendation_readiness","description":"Submit structured inputs to receive a readiness assessment. Read-only; no consequential actions are taken.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentInputs"}}}},"responses":{"200":{"description":"Successful assessment.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"result":{"$ref":"#/components/schemas/AssessmentResult"}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"string"}}}}}}}}}}},"components":{"schemas":{"AssessmentInputs":{"type":"object","properties":{"businessSize":{"type":"string","enum":["solo","micro","small","midmarket","enterprise"],"description":"Size of the business/organization."},"dataMaturity":{"type":"string","enum":["none","basic","developing","structured","advanced"],"description":"Availability and maturity of the structured/machine-readable data of the business."},"technicalStack":{"type":"string","enum":["minimal","standard","modern","advanced"],"description":"Technical stack / infrastructure sophistication."},"goals":{"type":"array","items":{"type":"string","enum":["ai_visibility","lead_generation","trust_authority","content_coverage","conversion_optimization","structured_data","agent_readiness","reputation_management"]},"minItems":1,"maxItems":8,"uniqueItems":true,"default":["ai_visibility"],"description":"One or more readiness goals the business wants to prioritize (1–8, unique values from the enum)."},"businessName":{"type":"string","description":"Optional, non-sensitive business name for context."},"industry":{"type":"string","description":"Optional industry/category for context."}},"required":["businessSize","dataMaturity","technicalStack"]},"AssessmentResult":{"type":"object","properties":{"tool":{"type":"string"},"engineVersion":{"type":"string"},"readinessScore":{"type":"number","description":"0-100 overall readiness score."},"tier":{"type":"object","properties":{"level":{"type":"integer"},"name":{"type":"string"},"summary":{"type":"string"}}},"dimensionScores":{"type":"array","items":{"type":"object"}},"gapAnalysis":{"type":"array","items":{"type":"object"}},"priorityActions":{"type":"array","items":{"type":"object"}},"implementationRoadmap":{"type":"array","items":{"type":"object"}},"normalizedInputs":{"type":"object"},"disclaimer":{"type":"string"}}}}}}