{"openapi":"3.1.0","info":{"title":"Beacon Agent Registry","description":"Beacon — Autonomous AI Agent Discovery & Reputation Registry.","version":"1.0.0"},"paths":{"/":{"get":{"summary":"Root","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Root  Get"}}}}}}},"/llms.txt":{"get":{"summary":"Llms Txt","description":"Web-standard LLM discovery doc (ClaudeBot, GPTBot, Grok, Perplexity, etc.). All metrics live.","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/ai-plugin.json":{"get":{"summary":"Ai Plugin","description":"OpenAI/Perplexity-style plugin manifest for programmatic discovery.","operationId":"ai_plugin__well_known_ai_plugin_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Ai Plugin  Well Known Ai Plugin Json Get"}}}}}}},"/beacon.cursorrules":{"get":{"summary":"Cursorrules","description":"Downloadable/scrapable Cursor rules that point the IDE at beacon-mcp.","operationId":"cursorrules_beacon_cursorrules_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Healthz Healthz Get"}}}}}}},"/api/v1/health":{"get":{"summary":"Api Health","description":"Lightweight health + live totals for frontend polling (every 30s).\nSingle COUNT(*) — sub-millisecond on indexed SQLite WAL.","operationId":"api_health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Api Health Api V1 Health Get"}}}}}}},"/api/admin/analytics-details":{"get":{"summary":"Admin Analytics Details","description":"Password-protected traffic and registry analytics (not for public UI).","operationId":"admin_analytics_details_api_admin_analytics_details_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Admin Analytics Details Api Admin Analytics Details Get"}}}}}}},"/discover/{slug}":{"get":{"summary":"Seo Discover","description":"Programmatic SEO landing page — live agent listings per capability.","operationId":"seo_discover_discover__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sitemap.xml":{"get":{"summary":"Seo Sitemap","operationId":"seo_sitemap_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/robots.txt":{"get":{"summary":"Seo Robots","operationId":"seo_robots_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/search":{"get":{"summary":"Search Agents","description":"Full-text search across name, mcp_endpoint (github URL), and capability tags.\nUses FTS5 with prefix matching; falls back to indexed LIKE for edge cases.\nSet include_total=true only when paginating — skips an extra COUNT for speed.\n\nBy default, clearly-dead repos (not pushed in 2+ years) are hidden to keep\nresults sharp for agent clients. Pass include_inactive=true for the full,\ncomprehensive set (stale repos included, still demoted by health_score).\n\nsort: relevance (default) | top (stars-led) | healthy (maintenance) | new\n      (freshest). min_stars sets a quality floor so tag searches surface\n      proven builders instead of ★0 tutorial repos.","operationId":"search_agents_api_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Inactive"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"relevance","title":"Sort"}},{"name":"min_stars","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Min Stars"}},{"name":"runnable_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Runnable Only"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Search Agents Api V1 Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/discovery":{"get":{"summary":"Discovery Tags","description":"Top tags & ecosystem categories — served from in-memory cache (refreshed hourly).\nNo per-request GROUP BY over 17k+ rows.","operationId":"discovery_tags_api_v1_discovery_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Discovery Tags Api V1 Discovery Get"}}}}}}},"/api/v1/agents/{agent_id}/beacon.json":{"get":{"summary":"Get Agent Beacon Manifest","description":"Generate a draft beacon.json for any indexed agent (copy into repo root).","operationId":"get_agent_beacon_manifest_api_v1_agents__agent_id__beacon_json_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{agent_id}":{"get":{"summary":"Get Agent","description":"Full agent profile + install manifest + metadata schema.","operationId":"get_agent_api_v1_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Agent Api V1 Agents  Agent Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/register":{"post":{"summary":"Register","description":"Self-Discovery hook. Atomic UPSERT: insert new, or refresh existing.\n\nSchedules an endpoint validation to run after the response is returned.","operationId":"register_api_v1_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Register Api V1 Register Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/manifest/validate":{"post":{"summary":"Manifest Validate","description":"Schema-check a Beacon Agent Manifest. No side effects.","operationId":"manifest_validate_api_v1_manifest_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestValidateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Manifest Validate Api V1 Manifest Validate Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/manifest/ingest":{"post":{"summary":"Manifest Ingest","description":"Fetch a manifest from a controlled location, validate it, and register the\nagent as a verified, self-declared entry. Location is the proof of ownership:\n  - <domain>/.well-known/beacon.json  -> domain verified\n  - a repo's raw beacon.json          -> repo verified","operationId":"manifest_ingest_api_v1_manifest_ingest_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestIngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Manifest Ingest Api V1 Manifest Ingest Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/manifest-scan":{"post":{"summary":"Manifest Scan","description":"Auto-adopt: walk indexed github repos and upgrade any that publish a\nbeacon.json to a verified, self-declared entry. Idempotent; cron a rolling\noffset to sweep the whole index, or pass ?owner=<org> to scan one org on\ndemand (e.g. after outreach). Admin-guarded (cheap raw GETs, no GH API).","operationId":"manifest_scan_api_admin_manifest_scan_post","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Manifest Scan Api Admin Manifest Scan Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/actionability-scan":{"post":{"summary":"Actionability Scan","description":"Enrich indexed github repos with HOW to invoke them (npx / pip). Rolling\noffset sweeps the index; ?owner= scans one org. Admin-guarded, cheap raw GETs.","operationId":"actionability_scan_api_admin_actionability_scan_post","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":150,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Actionability Scan Api Admin Actionability Scan Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/discover":{"post":{"summary":"Discover","description":"Capability search — FTS-backed (sub-second at 19k+ rows).\nFalls back to semantic synonym expansion via a second FTS query when sparse.","operationId":"discover_api_v1_discover_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Discover Api V1 Discover Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/telemetry":{"post":{"summary":"Telemetry","description":"Reputation engine. Accepts {\"agent_id\", \"status\": \"success\"|\"fail\"} and\natomically recomputes the agent's counters and success_rate in Turso:\n\n    total_transactions       += 1\n    successful_transactions  += (1 if success else 0)\n    success_rate              = successful_transactions / total_transactions\n\nRogue-metric guard: only a currently-registered agent_id can submit. The\nUPDATE ... WHERE agent_id = ? is a no-op for unknown ids, which we detect and\nreject with 404 — an unregistered/fake agent cannot move any ranking.","operationId":"telemetry_api_v1_telemetry_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Telemetry Api V1 Telemetry Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{agent_id}/badge.svg":{"get":{"summary":"Agent Badge","description":"Live SVG reputation badge for a developer's README. Regenerated per request so\nit reflects current telemetry. States: unknown (gray), flagged (crimson),\nverified (emerald with success %).","operationId":"agent_badge_api_v1_agents__agent_id__badge_svg_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/growth/trending":{"get":{"summary":"Growth Trending","description":"Trending agents this week — star milestones, surges, and recent pushes.\nPopulated by enrich_github.py; falls back to active high-traction repos.","operationId":"growth_trending_api_v1_growth_trending_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Growth Trending Api V1 Growth Trending Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/growth/proven":{"get":{"summary":"Growth Proven","description":"Top agents by real usage — telemetry jobs plus weighted portal/MCP selections.\nAgents with proven scores rank higher in discover/search tie-breakers.","operationId":"growth_proven_api_v1_growth_proven_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Growth Proven Api V1 Growth Proven Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/growth/usage-stats":{"get":{"summary":"Growth Usage Stats","description":"Public-safe aggregate: how many agents report telemetry vs get wired.","operationId":"growth_usage_stats_api_v1_growth_usage_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Growth Usage Stats Api V1 Growth Usage Stats Get"}}}}}}},"/api/v1/usage/select":{"post":{"summary":"Usage Select","description":"Record that an agent was selected (portal wire, MCP pick, orchestrator hook).\nIncrements proven score so listed agents benefit even before running the SDK.","operationId":"usage_select_api_v1_usage_select_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSelectRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Usage Select Api V1 Usage Select Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/radar":{"get":{"summary":"Radar","description":"Organic-adoption radar: the newest agents that registered via the SDK /\nauto-inject / Eliza plugins (registration_source = 'sdk'), newest first.\nLets us watch outside developers hit the platform in real time.","operationId":"radar_api_v1_radar_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Radar Api V1 Radar Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validate":{"post":{"summary":"Validate Batch","description":"Batch validator — the serverless-reliable path (call from cron). Re-checks the\nleast-recently-validated agents and persists reachability. On Vercel, the\nper-register BackgroundTask may be frozen after the response, so this endpoint\nguarantees validation coverage when hit on a schedule.","operationId":"validate_batch_api_v1_validate_post","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Validate Batch Api V1 Validate Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/leaderboard":{"get":{"summary":"Leaderboard","description":"Public leaderboard powering the homepage Top / Healthy / New / Proven tabs.\nsort: top (stars-led, default) | healthy | new | usage (telemetry jobs)\n      | proven (jobs + weighted selections). Dead repos (not pushed in 2+\n      years) are hidden unless include_inactive=true.","operationId":"leaderboard_api_v1_leaderboard_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"online_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Online Only"}},{"name":"include_flagged","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Flagged"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"top","title":"Sort"}},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Inactive"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Leaderboard Api V1 Leaderboard Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents":{"get":{"summary":"List Agents","description":"sort=top (reputation/stars), sort=recent (newest indexed), or sort=health\n(composite freshness+stars+issues — ranks maintained agents over dormant ones).","operationId":"list_agents_api_v1_agents_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"online_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Online Only"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"top","title":"Sort"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response List Agents Api V1 Agents Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"DiscoverRequest":{"properties":{"query":{"type":"string","maxLength":1024,"minLength":1,"title":"Query"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":25},"online_only":{"type":"boolean","title":"Online Only","default":false}},"type":"object","required":["query"],"title":"DiscoverRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ManifestIngestRequest":{"properties":{"url":{"type":"string","maxLength":2048,"minLength":8,"title":"Url"}},"type":"object","required":["url"],"title":"ManifestIngestRequest"},"ManifestValidateRequest":{"properties":{"manifest":{"type":"object","title":"Manifest"}},"type":"object","required":["manifest"],"title":"ManifestValidateRequest"},"RegisterRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id"},"name":{"type":"string","maxLength":256,"minLength":1,"title":"Name"},"mcp_endpoint":{"type":"string","maxLength":2048,"minLength":1,"title":"Mcp Endpoint"},"capabilities":{"type":"string","maxLength":4096,"title":"Capabilities","default":""},"source":{"type":"string","maxLength":32,"title":"Source","default":"sdk"},"stars":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Stars"},"open_issues":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Open Issues"},"pushed_at":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Pushed At"}},"type":"object","required":["agent_id","name","mcp_endpoint"],"title":"RegisterRequest"},"TelemetryRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id"},"status":{"type":"string","maxLength":32,"minLength":1,"title":"Status"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason"}},"type":"object","required":["agent_id","status"],"title":"TelemetryRequest"},"UsageSelectRequest":{"properties":{"agent_id":{"type":"string","maxLength":256,"minLength":1,"title":"Agent Id"},"source":{"type":"string","maxLength":32,"title":"Source","default":"portal"}},"type":"object","required":["agent_id"],"title":"UsageSelectRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}