{"openapi":"3.1.0","info":{"title":"AdAlign API","version":"1.0.0","description":"Evaluate the congruence between paid media ads and their landing pages. Uses AI vision analysis to score visual match, contextual alignment, and tone consistency."},"servers":[{"url":"https://app.adalign.io","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key with \"adal_\" prefix. Generate at Settings > API Keys."}},"schemas":{"EvaluationRequest":{"type":"object","required":["adData","landingPageData"],"properties":{"adData":{"type":"object","properties":{"imageUrl":{"type":"string","description":"URL of the ad image or creative. Either imageUrl or adUrl must be provided."},"adUrl":{"type":"string","description":"Direct URL to the ad (screenshotted automatically). Either imageUrl or adUrl must be provided."},"platform":{"type":"string","enum":["meta","tiktok","linkedin","google","reddit"],"description":"Ad platform. Affects scoring weights and platform-specific guidance."},"mediaType":{"type":"string","enum":["image","video","unknown"],"description":"Media type of the ad creative. Defaults to image."},"syncedAdId":{"type":"string","description":"ID of a synced ad from the Ad Library. Links the evaluation to the synced ad."}},"required":["platform"]},"landingPageData":{"type":"object","properties":{"url":{"type":"string","description":"Landing page URL to analyze"}},"required":["url"]},"viewport":{"type":"string","enum":["mobile","desktop"],"description":"Override the default viewport for landing page screenshots. Defaults to platform-appropriate viewport (mobile for Meta/TikTok, desktop for Google/LinkedIn)."}}},"EvaluationResponse":{"type":"object","properties":{"overallScore":{"type":"number","description":"Weighted overall alignment score (1-10)"},"componentScores":{"type":"object","description":"Penalty-adjusted scores per dimension","properties":{"visualMatch":{"type":"number","description":"Visual consistency (1-10)"},"contextualMatch":{"type":"number","description":"Average of messageMatch and aboveTheFoldContinuity (1-10)"},"toneAlignment":{"type":"number","description":"Tone and voice consistency (1-10)"},"messageMatch":{"type":"number","description":"Headline, offer, and CTA text alignment (1-10)"},"aboveTheFoldContinuity":{"type":"number","description":"Above-fold promise confirmation and path clarity (1-10)"},"informationScent":{"type":"number","description":"DEPRECATED — alias for aboveTheFoldContinuity. Use aboveTheFoldContinuity in new code; this field is removed in vNEXT.","deprecated":true}}},"rawScores":{"type":"object","description":"Scores before penalty adjustments (same shape as componentScores)"},"detailedScores":{"type":"object","description":"Band-first scoring with reasoning per dimension","properties":{"visualMatch":{"type":"object","properties":{"score":{"type":"number"},"band":{"type":"string","enum":["EXCEPTIONAL","GOOD","MODERATE","POOR","VERY_POOR"]},"reasoning":{"type":"string"}}},"messageMatch":{"type":"object","properties":{"score":{"type":"number"},"band":{"type":"string","enum":["EXCEPTIONAL","GOOD","MODERATE","POOR","VERY_POOR"]},"reasoning":{"type":"string"}}},"aboveTheFoldContinuity":{"type":"object","properties":{"score":{"type":"number"},"band":{"type":"string","enum":["EXCEPTIONAL","GOOD","MODERATE","POOR","VERY_POOR"]},"reasoning":{"type":"string"}}},"informationScent":{"type":"object","deprecated":true,"description":"DEPRECATED — alias for aboveTheFoldContinuity. Removed in vNEXT.","properties":{"score":{"type":"number"},"band":{"type":"string","enum":["EXCEPTIONAL","GOOD","MODERATE","POOR","VERY_POOR"]},"reasoning":{"type":"string"}}},"toneAlignment":{"type":"object","properties":{"score":{"type":"number"},"band":{"type":"string","enum":["EXCEPTIONAL","GOOD","MODERATE","POOR","VERY_POOR"]},"reasoning":{"type":"string"}}}}},"suggestions":{"type":"object","properties":{"visual":{"type":"array","items":{"type":"string"}},"contextual":{"type":"array","items":{"type":"string"}},"tone":{"type":"array","items":{"type":"string"}}}},"elementComparisons":{"type":"array","description":"10+ element-by-element comparisons between ad and landing page","items":{"type":"object","properties":{"element":{"type":"string"},"adValue":{"type":"string"},"landingPageValue":{"type":"string"},"status":{"type":"string","enum":["match","mismatch","partial_match","missing"]},"severity":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"recommendation":{"type":"string"}}}},"conversionRisks":{"type":"array","description":"Identified risks to conversion based on mismatches","items":{"type":"object","properties":{"risk":{"type":"string"},"severity":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"recommendation":{"type":"string"}}}},"fixes":{"type":"array","description":"AI-generated optimization suggestions with implementation guidance","items":{"type":"object","properties":{"fixType":{"type":"string"},"target":{"type":"string","enum":["ad","landing_page"]},"priority":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"suggestedValue":{"type":"string"},"reasoning":{"type":"string"},"expectedImpact":{"type":"string"},"effort":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}}}},"evaluationId":{"type":"string"},"adScreenshotUrl":{"type":"string"},"landingPageScreenshotUrl":{"type":"string","nullable":true},"alternateScreenshotUrl":{"type":"string","nullable":true,"description":"Screenshot from the alternate viewport"},"alternateViewport":{"type":"string","nullable":true,"enum":["mobile","desktop"]},"analysisModel":{"type":"string","description":"AI model used for analysis (e.g. gemini-3-pro-preview, gemini-2.5-flash)"},"mediaType":{"type":"string","enum":["image","video"]},"viewport":{"type":"string","enum":["mobile","desktop"]},"pageSpeedData":{"type":"object","nullable":true,"description":"PageSpeed Insights data for the landing page","properties":{"performanceScore":{"type":"number"},"lcp":{"type":"number"},"cls":{"type":"number"},"tbt":{"type":"number"}}},"videoMetadata":{"type":"object","nullable":true,"description":"Present only for video ad evaluations","properties":{"frameCount":{"type":"number"},"processingMethod":{"type":"string"},"hasTranscript":{"type":"boolean"},"transcriptLength":{"type":"number"},"videoDuration":{"type":"number","nullable":true}}}}},"UsageInfo":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"},"canEvaluate":{"type":"boolean"},"nextReset":{"type":"string","format":"date-time"},"tier":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"errorCode":{"type":"string"}}}}},"paths":{"/api/analyze-ad":{"post":{"summary":"Evaluate ad-to-landing page alignment","description":"Run an AI vision analysis comparing an ad creative with its landing page. Returns visual match, contextual alignment, and tone consistency scores with actionable recommendations.","operationId":"analyzeAd","tags":["Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationRequest"}}}},"responses":{"200":{"description":"Evaluation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationResponse"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"429":{"description":"Rate limit exceeded"}}}},"/api/check-usage":{"get":{"summary":"Check remaining evaluations","description":"Returns usage information for the authenticated user including remaining evaluations and tier.","operationId":"checkUsage","tags":["Usage"],"responses":{"200":{"description":"Usage information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageInfo"}}}}}}},"/api/user-history":{"get":{"summary":"List past evaluations","description":"Returns the authenticated user's evaluation history ordered by most recent.","operationId":"getUserHistory","tags":["History"],"responses":{"200":{"description":"Evaluation history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"evaluations":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}}}}}}}},"/api/fixes":{"get":{"summary":"Get AI-generated fixes for an evaluation","description":"Returns optimization suggestions for a specific evaluation.","operationId":"getFixes","tags":["Fixes"],"parameters":[{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["list","get","stats"]}},{"name":"evaluationId","in":"query","schema":{"type":"string"},"description":"Required for action=list"}],"responses":{"200":{"description":"Fixes data"}}}}}}