{"openapi":"3.0.3","info":{"title":"BEACON AI — AEO API","version":"1.0.0","description":"BEACON AI measures brand visibility across AI systems including ChatGPT, Claude, Gemini, Perplexity, and Copilot. Use this API to retrieve AI Visibility Scores, per-platform breakdowns, competitive category data, and historical trends. Get your API key at www.usebeacon.in/dashboard → Settings → API Keys.","contact":{"name":"BEACON AI","url":"https://www.usebeacon.in/connect"},"license":{"name":"Commercial","url":"https://www.usebeacon.in/terms"}},"servers":[{"url":"https://www.usebeacon.in","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Visibility","description":"AI Visibility Scores and full audit reports"},{"name":"Category","description":"Competitive category rank and Share of Voice"},{"name":"History","description":"Historical score trends across multiple audits"}],"paths":{"/api/v1/report":{"get":{"operationId":"getVisibilityReport","summary":"Get AI Visibility Report","description":"Returns the latest AI Visibility Score (0–100) and full report for a brand domain, including per-platform scores, Share of Voice against competitors, and the top recommendation.","tags":["Visibility"],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","example":"boat-lifestyle.com"},"description":"Brand domain to query, e.g. boat-lifestyle.com"}],"responses":{"200":{"description":"AI Visibility Report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityReport"},"example":{"id":"a1b2c3","brand_name":"boAt","domain":"boat-lifestyle.com","audited_at":"2026-10-18T10:00:00Z","overall_score":72,"mention_rate":65,"platforms":[{"platform":"chatgpt","score":78,"mention_count":14,"avg_rank":2},{"platform":"claude","score":70,"mention_count":12,"avg_rank":2},{"platform":"gemini","score":65,"mention_count":11,"avg_rank":3},{"platform":"perplexity","score":74,"mention_count":13,"avg_rank":2},{"platform":"copilot","score":68,"mention_count":10,"avg_rank":3}],"share_of_voice":{"target_pct":34,"total_mentions":120,"competitors":[{"name":"Sony","mention_count":45,"share_pct":38}]},"insights_count":7,"top_insight":{"priority":"high","title":"Deploy agent.json","description":"Add agent.json to your domain root so AI systems can read structured brand data.","category":"Discoverability"}}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"No audit found for this domain"}}}},"/api/v1/category":{"get":{"operationId":"getCategoryIntelligence","summary":"Get category competitive rank","description":"Returns the brand's rank within its product category based on AI Share of Voice — how often AI systems mention this brand versus competitors — and the full category leaderboard.","tags":["Category"],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","example":"boat-lifestyle.com"},"description":"Brand domain, e.g. boat-lifestyle.com"}],"responses":{"200":{"description":"Category Intelligence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryIntelligence"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"No competitive data for this domain"}}}},"/api/v1/audits":{"get":{"operationId":"getAuditHistory","summary":"Get audit history","description":"Returns a list of past audits for a domain (most recent first), showing score trends over time. Useful for tracking whether AI visibility is improving after optimisation work.","tags":["History"],"parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string","example":"boat-lifestyle.com"},"description":"Filter by domain (optional — omit to return all audits)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Maximum number of audits to return"}],"responses":{"200":{"description":"Audit history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditHistory"}}}},"401":{"description":"Invalid or missing API key"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"BEACON API key — create one at www.usebeacon.in/dashboard → Settings → API Keys. Format: Authorization: Bearer bk_live_<key>"}},"schemas":{"PlatformScore":{"type":"object","properties":{"platform":{"type":"string","enum":["chatgpt","claude","gemini","perplexity","copilot","grok"],"description":"AI platform identifier"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Visibility score 0–100"},"mention_count":{"type":"integer","description":"Queries where brand was mentioned"},"avg_rank":{"type":"number","nullable":true,"description":"Average rank when mentioned (1 = top)"}}},"Insight":{"type":"object","properties":{"priority":{"type":"string","enum":["high","medium","low"]},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"}}},"VisibilityReport":{"type":"object","properties":{"id":{"type":"string"},"brand_name":{"type":"string"},"domain":{"type":"string"},"audited_at":{"type":"string","format":"date-time"},"overall_score":{"type":"integer","minimum":0,"maximum":100,"description":"Composite AI Visibility Score 0–100"},"mention_rate":{"type":"integer","minimum":0,"maximum":100,"description":"Percentage of queries where brand was mentioned"},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/PlatformScore"}},"share_of_voice":{"type":"object","nullable":true,"properties":{"target_pct":{"type":"integer","description":"Brand's share of AI mentions in category (%)"},"total_mentions":{"type":"integer"},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"mention_count":{"type":"integer"},"share_pct":{"type":"integer"}}}}}},"insights_count":{"type":"integer"},"top_insight":{"nullable":true,"$ref":"#/components/schemas/Insight"}}},"CategoryIntelligence":{"type":"object","properties":{"domain":{"type":"string"},"brand_name":{"type":"string"},"audited_at":{"type":"string","format":"date-time"},"category_rank":{"type":"integer","description":"1-indexed rank in category"},"total_brands_tracked":{"type":"integer"},"target_share_pct":{"type":"integer"},"total_mentions_in_category":{"type":"integer"},"leaderboard":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"mention_count":{"type":"integer"},"share_pct":{"type":"integer"},"is_target":{"type":"boolean"}}}}}},"AuditHistory":{"type":"object","properties":{"total":{"type":"integer"},"audits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brand_name":{"type":"string"},"domain":{"type":"string"},"audited_at":{"type":"string","format":"date-time"},"overall_score":{"type":"integer"},"mention_rate":{"type":"integer"},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"score":{"type":"integer"}}}}}}}}}}}}