{"openapi":"3.1.0","info":{"title":"PlatPhorm Insights API","version":"2.0.0","description":"AI-First web performance analysis API. Part of the PlatPhorm News Network. Includes advanced AI-era scoring for SEO, AEO, and GEO optimization.","contact":{"name":"PlatPhorm News Network","url":"https://platphormnews.com","email":"api@platphormnews.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"x-mcp-endpoints":["https://mcp.platphormnews.com","https://trace.platphormnews.com/api/mcp"]},"servers":[{"url":"https://insights.platphormnews.com","description":"Production"},{"url":"https://trace.platphormnews.com","description":"Trace Server"}],"paths":{"/api/v1/analyze":{"post":{"summary":"Analyze URL","description":"Run a comprehensive performance, accessibility, SEO, and best practices analysis on a URL. Includes AI-era scoring for readability, searchability, answerability, and audience fit.","operationId":"analyzeUrl","tags":["Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL to analyze"},"strategy":{"type":"string","enum":["mobile","desktop"],"default":"mobile"},"categories":{"type":"array","items":{"type":"string","enum":["performance","accessibility","seo","best-practices"]}},"locale":{"type":"string","default":"en"},"includeAI":{"type":"boolean","default":true,"description":"Include AI-powered recommendations"},"includeCarbon":{"type":"boolean","default":true,"description":"Include carbon footprint analysis"},"includeSecurity":{"type":"boolean","default":true,"description":"Include security headers analysis"},"includeAdvancedScoring":{"type":"boolean","default":true,"description":"Include AI-era scoring (readability, searchability, answerability, audience)"}}}}}},"responses":{"200":{"description":"Analysis completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisResponse"}}}},"400":{"description":"Invalid request"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Analysis failed"}}}},"/api/v1/results/{id}":{"get":{"summary":"Get Analysis Results","description":"Retrieve results of a previously run analysis.","operationId":"getResults","tags":["Analysis"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analysis results"},"404":{"description":"Analysis not found"}}}},"/api/v1/compare":{"post":{"summary":"Compare URLs","description":"Compare performance metrics across multiple URLs.","operationId":"compareUrls","tags":["Comparison"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":2,"maxItems":5},"strategy":{"type":"string","enum":["mobile","desktop"],"default":"mobile"}}}}}},"responses":{"200":{"description":"Comparison results"},"400":{"description":"Invalid request"}}}},"/api/v1/timeline":{"get":{"summary":"Public Analysis Timeline","description":"Get the public timeline of all analyzed websites.","operationId":"getTimeline","tags":["Timeline"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"minScore","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Timeline entries"}}}},"/api/v1/scoring/readability":{"post":{"summary":"Readability Score","description":"Calculate readability metrics including Flesch-Kincaid, SMOG, Gunning Fog, and Coleman-Liau scores.","operationId":"getReadabilityScore","tags":["AI-Era Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Readability scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadabilityScore"}}}}}}},"/api/v1/scoring/searchability":{"post":{"summary":"Searchability Score","description":"Analyze content discoverability for search engines and AI systems.","operationId":"getSearchabilityScore","tags":["AI-Era Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Searchability scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchabilityScore"}}}}}}},"/api/v1/scoring/answerability":{"post":{"summary":"Answerability Score","description":"Measure content suitability for AI answer engines (ChatGPT, Perplexity, Google AI Overview).","operationId":"getAnswerabilityScore","tags":["AI-Era Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Answerability scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerabilityScore"}}}}}}},"/api/v1/scoring/audience":{"post":{"summary":"Audience Score","description":"Analyze content targeting and engagement signals for different user segments.","operationId":"getAudienceScore","tags":["AI-Era Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Audience scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceScore"}}}}}}},"/api/v1/llm-instructions":{"post":{"summary":"LLM Instructions","description":"Generate comprehensive LLM-centric instruction set for website improvement.","operationId":"getLLMInstructions","tags":["AI-Era Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"LLM instruction set"}}}},"/api/mcp":{"get":{"summary":"MCP Tool Manifest","description":"Get available MCP tools for AI agent integration. No API key required.","operationId":"getMcpManifest","tags":["MCP"],"responses":{"200":{"description":"MCP tool manifest with 12 available tools"}}},"post":{"summary":"Execute MCP Tool","description":"Execute an MCP tool call. Supports all analysis and scoring tools.","operationId":"executeMcpTool","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method","params"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"method":{"type":"string","enum":["tools/list","tools/call"]},"params":{"type":"object"},"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Tool execution result"}}}},"/api/health":{"get":{"summary":"Health Check","description":"Check API and database health status.","operationId":"healthCheck","tags":["System"],"responses":{"200":{"description":"System is healthy"},"503":{"description":"System is unhealthy"}}}},"/llms.txt":{"get":{"summary":"LLMs.txt","description":"Machine-readable discovery document for AI systems.","operationId":"getLlmsTxt","tags":["Discovery"],"responses":{"200":{"description":"LLMs.txt content"}}}}},"components":{"schemas":{"AnalysisResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"strategy":{"type":"string"},"scores":{"$ref":"#/components/schemas/LighthouseScores"},"coreWebVitals":{"$ref":"#/components/schemas/CoreWebVitals"},"advancedScores":{"$ref":"#/components/schemas/AdvancedScores"},"aiRecommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"carbonFootprint":{"type":"object"},"securityHeaders":{"type":"object"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"duration":{"type":"number"}}}}},"LighthouseScores":{"type":"object","properties":{"performance":{"type":"integer","minimum":0,"maximum":100},"accessibility":{"type":"integer","minimum":0,"maximum":100},"seo":{"type":"integer","minimum":0,"maximum":100},"bestPractices":{"type":"integer","minimum":0,"maximum":100}}},"CoreWebVitals":{"type":"object","properties":{"lcp":{"$ref":"#/components/schemas/MetricValue"},"inp":{"$ref":"#/components/schemas/MetricValue"},"cls":{"$ref":"#/components/schemas/MetricValue"},"fcp":{"$ref":"#/components/schemas/MetricValue"},"ttfb":{"$ref":"#/components/schemas/MetricValue"}}},"MetricValue":{"type":"object","properties":{"value":{"type":"number"},"rating":{"type":"string","enum":["good","needs-improvement","poor"]},"unit":{"type":"string"}}},"AdvancedScores":{"type":"object","properties":{"readability":{"$ref":"#/components/schemas/ReadabilityScore"},"searchability":{"$ref":"#/components/schemas/SearchabilityScore"},"answerability":{"$ref":"#/components/schemas/AnswerabilityScore"},"audience":{"$ref":"#/components/schemas/AudienceScore"},"llmInstructions":{"type":"object"}}},"ReadabilityScore":{"type":"object","properties":{"overall":{"type":"integer","minimum":0,"maximum":100},"fleschKincaid":{"type":"number"},"smogIndex":{"type":"number"},"gunningFog":{"type":"number"},"colemanLiau":{"type":"number"},"avgSentenceLength":{"type":"number"},"avgSyllablesPerWord":{"type":"number"}}},"SearchabilityScore":{"type":"object","properties":{"overall":{"type":"integer","minimum":0,"maximum":100},"metaScore":{"type":"integer"},"structuredDataScore":{"type":"integer"},"semanticScore":{"type":"integer"},"linkingScore":{"type":"integer"}}},"AnswerabilityScore":{"type":"object","properties":{"overall":{"type":"integer","minimum":0,"maximum":100},"questionCoverage":{"type":"integer"},"contentClarity":{"type":"integer"},"citabilityScore":{"type":"integer"},"structureScore":{"type":"integer"}}},"AudienceScore":{"type":"object","properties":{"overall":{"type":"integer","minimum":0,"maximum":100},"expertiseLevel":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"engagementSignals":{"type":"integer"},"accessibilityScore":{"type":"integer"}}},"Recommendation":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"priority":{"type":"string","enum":["critical","high","medium","low"]},"impact":{"type":"string"},"effort":{"type":"string"},"category":{"type":"string"}}}}},"tags":[{"name":"Analysis","description":"Performance analysis endpoints"},{"name":"Comparison","description":"URL comparison endpoints"},{"name":"AI-Era Scoring","description":"Advanced scoring for SEO, AEO, and GEO optimization"},{"name":"Timeline","description":"Public analysis timeline"},{"name":"MCP","description":"Model Context Protocol integration - no API key required"},{"name":"Discovery","description":"Machine-readable discovery endpoints"},{"name":"System","description":"System and health endpoints"}]}