{ "openapi": "3.1.0", "info": { "title": "Git.Top Agent API", "version": "0.1.0", "description": "Agent-native GitHub project knowledge API for search, project lookup, alternatives, comparison, graph reasoning, quality, and schema discovery. High-confidence clients should inspect metadata.source, metadata.reason, trust fields, classification evidence, quality_signal_confidence, verification signals, and migration validation steps, and use require_d1=true when seed fallback should fail closed." }, "servers": [ { "url": "https://git.top", "description": "Production" }, { "url": "http://localhost:8787", "description": "Local Worker" } ], "paths": { "/api/health": { "get": { "summary": "Inspect D1 availability, project counts, and sync freshness.", "responses": { "200": { "description": "Health response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "ok": true, "db": "available", "project_count": 500, "raw_project_count": 500, "knowledge_ready_project_count": 500, "sync_health": "healthy", "sync_freshness": "fresh", "last_successful_sync_at": "2026-07-04T00:00:00.000Z", "hours_since_successful_sync": 1, "operational_storage": { "status": "healthy", "github_cache_entries": 1200, "github_cache_body_bytes": 32000000, "github_cache_max_entries": 2500, "github_cache_retention_entries": 1500, "github_cache_body_budget_bytes": 163840000, "utilization": 0.48, "star_snapshot_count": 500, "sync_run_count": 120, "governance_run_count": 40 }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/trust": { "get": { "summary": "Fetch the production-readiness Trust Gate for high-confidence agent recommendations.", "parameters": [ { "name": "detail", "in": "query", "required": false, "description": "Response detail level: summary (default) omits quality issue rows; full includes them and larger sync previews", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trust Gate decision with checks, agent policy, health, sync, quality summary, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustGateResponse" }, "example": { "name": "Git.Top Trust Gate", "decision": "allow", "production_ready": true, "freshness_slo": { "hot_projects": { "target_hours": 48, "total": 80, "within_target": 77, "freshness_rate": 0.963, "target_rate": 0.95, "meets_target": true }, "whole_corpus": { "target_basis": "tier_policy", "total": 500, "within_target": 493, "freshness_rate": 0.986, "target_rate": 0.95, "meets_target": true } }, "checks": [ { "id": "d1-source", "label": "D1-backed source", "status": "pass", "observed": "available / d1", "requirement": "db=available and metadata.source=d1" }, { "id": "hot-corpus-freshness", "label": "Hot corpus freshness", "status": "pass", "observed": "77/80 within 48h (96%)", "requirement": "hot_project_freshness_rate>=0.95" }, { "id": "sync-capacity", "label": "Scheduled sync capacity", "status": "pass", "observed": "100/336 required daily", "requirement": "sync_capacity_target_feasible=true" } ], "required_for_high_confidence": [ "metadata.source=d1", "db=available", "sync_freshness=fresh", "hot_project_freshness_rate>=0.95", "sync_capacity_target_feasible=true" ], "agent_policy": { "cite": [ "metadata.source", "sync_freshness", "hot_project_freshness_rate", "whole_corpus_freshness_rate", "sync_capacity_target_feasible", "data_trust_score" ], "disclose_when": [ "seed fallback is active", "sync is stale or degraded", "hot-tier corpus freshness is outside target" ] }, "health": { "ok": true, "db": "available", "project_count": 500, "raw_project_count": 500, "knowledge_ready_project_count": 500, "sync_health": "healthy", "sync_freshness": "fresh", "last_successful_sync_at": "2026-07-04T00:00:00.000Z", "hours_since_successful_sync": 1, "operational_storage": { "status": "healthy", "github_cache_entries": 1200, "github_cache_body_bytes": 32000000, "github_cache_max_entries": 2500, "github_cache_retention_entries": 1500, "github_cache_body_budget_bytes": 163840000, "utilization": 0.48, "star_snapshot_count": 500, "sync_run_count": 120, "governance_run_count": 40 }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } }, "sync": { "health": "healthy", "freshness": "fresh", "priority": { "counts": { "hot": 80, "warm": 300, "cold": 120 }, "refresh_due_counts": { "hot": 4, "warm": 6, "cold": 0 }, "stale_counts": { "hot": 3, "warm": 4, "cold": 0 }, "stale_rates": { "hot": 0.038, "warm": 0.013, "cold": 0 }, "freshness_slo": { "hot_projects": { "target_hours": 48, "total": 80, "within_target": 77, "freshness_rate": 0.963, "target_rate": 0.95, "meets_target": true }, "whole_corpus": { "target_basis": "tier_policy", "total": 500, "within_target": 493, "freshness_rate": 0.986, "target_rate": 0.95, "meets_target": true } }, "capacity": { "scheduled_daily_capacity": 336, "required_daily_syncs": 100, "utilization": 0.298, "headroom": 236, "target_feasible": true } } }, "quality": { "score": 96, "release_score": 96, "data_trust_score": 82, "score_summary": { "release_score_meaning": "Release gate score.", "data_trust_score_meaning": "Corpus trust score.", "risk_level_meaning": "Risk level summarizes corpus confidence." }, "risk_level": "low", "risk_summary": { "level": "low", "reasons": [], "low_confidence_classification_rate": 0.04, "collection_review_rate": 0.02, "stale_project_rate": 0.01, "stale_collection_rate": 0 }, "coverage": { "covered_categories": 14, "total_categories": 14, "missing_categories": [] }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/agent-map": { "get": { "summary": "Map Git.Top concepts to human pages, REST endpoints, MCP tools, output fields, trust fields, and recommended use.", "responses": { "200": { "description": "Agent surface map for REST, MCP, and human page discovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMapResponse" } } } } } } }, "/api/compatibility": { "get": { "summary": "Fetch dated MCP client compatibility evidence and distinguish configuration verification from real-client support.", "responses": { "200": { "description": "Client compatibility matrix, generic server-contract status, support policy, and known limitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCompatibilityResponse" }, "example": { "schema_version": "git-top.client-compatibility.v1", "last_reviewed_at": "2026-07-31", "core_endpoint": "https://git.top/mcp/core", "support_policy": "A client is supported only after all required production checks pass.", "server_contract": { "initialize": "passed", "core_tool_discovery": "passed", "first_core_call": "passed", "production_smoke": "passed" }, "clients": [ { "client": "Codex CLI, app, and IDE", "version": "0.145.0", "support_level": "supported", "initialize": "passed", "tool_discovery": "passed", "first_call": "passed", "multi_tool_workflow": "passed", "error_behavior": "passed" }, { "client": "Claude Code", "version": "2.1.220", "support_level": "supported", "initialize": "passed", "tool_discovery": "passed", "first_call": "passed", "multi_tool_workflow": "passed", "error_behavior": "passed" } ] } } } } } } }, "/api/roadmap": { "get": { "summary": "Inspect Git.Top 2.0 product roadmap progress, shipped surfaces, active work, human pages, REST endpoints, and MCP coverage.", "responses": { "200": { "description": "Product roadmap with completion, phases, shipped work, next milestones, agent use guidance, pages, APIs, and MCP tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoadmapResponse" }, "example": { "positioning": "The Knowledge Graph of Open Source", "summary": "Git.Top is expanding agent-native project selection surfaces.", "completion": 92, "current_focus": [ "agent-api", "quality" ], "phases": [ { "id": "agent-api", "status": "shipped", "progress": 100, "api_endpoints": [ "/api/agent-map" ] } ], "agent_use": [ "Use /api/agent-map to choose the right surface." ], "pages": [ "/docs", "/trust", "/benchmark" ], "api_endpoints": [ "/api/agent-map", "/api/benchmark" ], "mcp_tools": [ "get_project", "get_public_benchmark" ] } } } } } } }, "/api/quickstart": { "get": { "summary": "Fetch the Git.Top Agent Quickstart with REST, MCP, GRP, command examples, trust fields, and output pattern.", "responses": { "200": { "description": "Agent quickstart with ordered steps, Atlas journey guidance, endpoint examples, inspection fields, trust policy, and answer pattern", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickstartResponse" }, "example": { "positioning": "The Knowledge Graph of Open Source", "production_endpoints": { "rest": "https://git.top", "mcp": "https://git.top/mcp", "mcp_core": "https://git.top/mcp/core" }, "steps": [ { "id": "trust", "rest": "GET /api/trust", "inspect": [ "decision", "metadata.source" ] } ], "output_pattern": [ "Cite metadata.source and evidence fields." ], "trust_policy": [ "Use require_d1=true for fail-closed production reads." ] } } } } } } }, "/api/recipes": { "get": { "summary": "Fetch executable Git.Top agent recipes for common project selection, alternatives, comparison, graph, Atlas journeys, quality, and GRP tasks.", "responses": { "200": { "description": "Agent recipes with use cases, outcomes, ordered REST steps, Atlas comparison path examples, command examples, inspection fields, and trust checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipesResponse" }, "example": { "positioning": "The Knowledge Graph of Open Source", "recipes": [ { "id": "choose-cloudflare-agent-framework", "outcome": "Shortlist Cloudflare-ready agent frameworks.", "steps": [ { "endpoint": "/api/recommend" } ] } ], "trust_policy": [ "Check /api/trust before high-confidence recommendations." ] } } } } } } }, "/api/examples": { "get": { "summary": "Fetch copyable REST, MCP, and GRP examples for common agent workflows.", "responses": { "200": { "description": "Agent API examples with commands, inspection fields, trust checks, and next actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExamplesResponse" }, "example": { "positioning": "The Knowledge Graph of Open Source", "decision_examples": [ { "id": "choose-cloudflare-agent-framework", "title": "Choose an agent framework for Cloudflare Workers", "user_request": "Choose an open-source agent framework that can run on Cloudflare Workers and explain the evidence.", "shortest_rest_path": [ "GET /api/trust", "POST /api/workflow", "GET /api/project/cloudflare/agents" ], "shortest_mcp_path": [ "get_agent_workflow", "get_project" ], "expected_fields": [ "shortlist", "decision_summary", "classification", "caveats", "metadata.source" ], "example_final_answer": "For this Cloudflare-specific target, cloudflare/agents is the current shortlist match with high recommendation confidence and matched deployment, category, and Cloudflare-readiness constraints. The project record says it is designed for Cloudflare-native, stateful agents. Caveat: classification and several quality signals are low-confidence or partial, so verify the deployment guide and run a Workers proof of concept before adoption.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Inspect the repository deployment instructions and compare a proof of concept against any non-Workers runtime requirement." }, { "id": "compare-local-coding-agents", "title": "Compare two coding agents for local use", "user_request": "Compare Codex and OpenCode for a local coding-agent workflow.", "shortest_rest_path": [ "GET /api/trust", "POST /api/compare" ], "shortest_mcp_path": [ "compare_projects" ], "expected_fields": [ "context", "decision_matrix", "winner", "reasoning", "metadata.snapshot_id" ], "example_final_answer": "For the local-deployment context in this snapshot, openai/codex ranks ahead of anomalyco/opencode. Both match the local preference. Caveat: both carry a 24/100 maintenance signal in the current comparison. Treat Codex as the contextual leader, not a universal winner, and inspect recent releases and issue activity for both before choosing.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Run the same representative repository task in both clients and compare tool reliability, edit quality, and operational cost." }, { "id": "check-unfamiliar-dependency", "title": "Check an unfamiliar dependency before adding it", "user_request": "Should I add cloudflare/agents to a Python-first agent stack?", "shortest_rest_path": [ "GET /api/trust", "GET /api/project/cloudflare/agents" ], "shortest_mcp_path": [ "get_project" ], "expected_fields": [ "summary.good_for", "summary.not_good_for", "classification", "quality_signal_confidence", "caveats" ], "example_final_answer": "Do not select cloudflare/agents by default for a Python-first stack. Its strongest fit is Cloudflare-native, stateful agents on Workers, while the project summary explicitly lists Python-first stacks as a poor fit. Caveat: the current record has incomplete classification and quality evidence, so confirm language and integration requirements in the upstream repository before ruling it in or out.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Confirm whether the application can use a TypeScript Workers boundary; otherwise compare a Python-native framework." }, { "id": "find-langchain-alternative", "title": "Find a credible LangChain alternative", "user_request": "Find maintained alternatives to LangChain and distinguish direct replacements from adjacent options.", "shortest_rest_path": [ "GET /api/trust", "GET /api/alternatives/langchain", "POST /api/compare" ], "shortest_mcp_path": [ "get_alternatives", "compare_projects" ], "expected_fields": [ "alternative_matches", "fit_summary", "replacement_risk", "caveats", "metadata.source" ], "example_final_answer": "superagent-ai/superagent is the top direct alternative in this snapshot, with 93/100 similarity and low replacement risk. TransformerOptimus/SuperAGI is another direct-category candidate. run-llama/llama_index is adjacent rather than drop-in because its category differs. Caveat: estimated activity signals and API compatibility still need upstream verification.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Compare the top direct candidate with LangChain against the exact integrations, deployment model, and migration surface you use." }, { "id": "choose-docker-vector-database", "title": "Choose a vector database for Docker", "user_request": "Recommend a vector database that can be self-hosted with Docker.", "shortest_rest_path": [ "GET /api/trust", "POST /api/recommend", "POST /api/compare" ], "shortest_mcp_path": [ "recommend_project", "compare_projects" ], "expected_fields": [ "recommendations", "matched_constraints", "risk_flags", "confidence", "caveats" ], "example_final_answer": "Redis and Milvus are tied at 62/100 in this Docker-constrained snapshot, with Qdrant close behind at 61/100; all are medium-confidence exploration candidates. Do not choose from score alone. Each carries a weak maintenance warning in the indexed evidence and is unsuitable for edge-only Workers deployment without adaptation.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Compare operational footprint, filtering requirements, scale, backup model, and client-language support before running a workload benchmark." }, { "id": "replace-archived-python-agent-framework", "title": "Replace an archived Python agent framework", "user_request": "Find a maintained replacement for the archived microsoft/TaskWeaver project for local Python tool execution.", "shortest_rest_path": [ "GET /api/trust", "POST /api/recommend", "GET /api/project/langchain-ai/langchain", "POST /api/compare" ], "shortest_mcp_path": [ "recommend_project", "get_project", "compare_projects" ], "expected_fields": [ "recommendations", "matched_constraints", "confidence", "classification", "caveats", "metadata.snapshot_id", "external_evidence" ], "example_final_answer": "GitHub reports microsoft/TaskWeaver as archived. For a local Python agent-framework replacement, Git.Top ranks langchain-ai/langchain first at 65/100 with medium confidence, followed by pydantic/pydantic-ai at 45/100 with medium confidence. Caveat: this is not a drop-in compatibility claim; LangChain's indexed classification is low-confidence and the candidates need API, tool-execution, and migration testing against the TaskWeaver workload.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "external_evidence": [ { "source": "github_api", "subject": "microsoft/TaskWeaver", "verified_at": "2026-07-31", "url": "https://api.github.com/repos/microsoft/TaskWeaver", "facts": [ "archived=true", "disabled=false" ] } ], "next_action": "List the TaskWeaver APIs and execution behaviors in use, then run the same tool task in LangChain and Pydantic AI before selecting a migration target." }, { "id": "choose-local-llm-runtime", "title": "Choose a local LLM runtime", "user_request": "Choose among Ollama, llama.cpp, and GPT4All for a local inference workflow.", "shortest_rest_path": [ "GET /api/trust", "GET /api/search", "POST /api/compare", "GET /api/project/ollama/ollama" ], "shortest_mcp_path": [ "search_projects", "compare_projects", "get_project" ], "expected_fields": [ "projects", "decision_matrix", "winner", "classification", "quality_signal_confidence", "caveats", "metadata.snapshot_id" ], "example_final_answer": "For the local-deployment context in this snapshot, ollama/ollama is the contextual winner over ggml-org/llama.cpp and nomic-ai/gpt4all. All three have a 79/100 Git.Top score and a 24/100 maintenance signal; llama.cpp has the strongest indexed category confidence. Caveat: the comparison does not model hardware, quantization, model-format, or throughput requirements, so Ollama is a workflow starting point rather than a universal runtime winner.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Benchmark the same model and prompt set on target hardware, including memory use, startup time, throughput, model-format support, and API compatibility." }, { "id": "choose-github-automation-mcp-server", "title": "Choose an MCP server for GitHub automation", "user_request": "Choose an MCP server for repository and pull-request automation on GitHub.", "shortest_rest_path": [ "GET /api/trust", "GET /api/search", "GET /api/project/github/github-mcp-server" ], "shortest_mcp_path": [ "search_projects", "get_project" ], "expected_fields": [ "projects", "project_id", "summary", "classification", "git_top_score", "quality_score", "caveats", "metadata.source" ], "example_final_answer": "github/github-mcp-server is the exact-purpose candidate in this snapshot: its indexed description is an MCP server for GitHub developer tools, its MCP-server classification is high-confidence, and its Git.Top score is 79/100. Caveat: its quality score is 43/100, maintenance signal is 24/100, and the generic recommender gives this exact use case low confidence. Prefer it for a proof of concept because of purpose fit, then validate authentication scopes and every mutation tool before operational use.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Connect it with a least-privilege test token and verify read-only repository queries before testing issue or pull-request mutations in a disposable repository." }, { "id": "assemble-rag-stack-with-observability", "title": "Assemble a RAG stack with observability", "user_request": "Draft a self-hosted Docker RAG stack with observability and provide citable trust evidence.", "shortest_rest_path": [ "GET /api/trust", "POST /api/grp/query", "GET /api/project/run-llama/llama_index", "GET /api/project/SigNoz/signoz" ], "shortest_mcp_path": [ "get_trust_gate", "git_top_grp_query", "get_project" ], "expected_fields": [ "decision", "checks", "solution_paths", "recommended_stack", "stack_roles", "tradeoffs", "metadata.data_source", "caveats" ], "example_final_answer": "Use the GRP result only as an architecture draft: LlamaIndex fills the memory role, LangChain the agent-core role, Docker the runtime, and SigNoz the observability role. The leading path scores 72/100. Do not present this as production-ready: the Trust Gate is block because sync and hot-corpus freshness fail, and the bounded graph reports missing or weak protocol, tool-execution, and LLM-access coverage.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Pin one project per required role, verify supported integrations and licenses upstream, then build a traced ingestion-and-retrieval proof of concept before re-running the trust gate." }, { "id": "distinguish-collection-from-project", "title": "Distinguish a collection from an executable project", "user_request": "Can I adopt run-llama/awesome-rag as my RAG runtime, or should I use LlamaIndex?", "shortest_rest_path": [ "GET /api/trust", "GET /api/project/run-llama/awesome-rag", "GET /api/project/run-llama/llama_index", "POST /api/compare" ], "shortest_mcp_path": [ "get_project", "compare_projects" ], "expected_fields": [ "project_kind", "collection_metadata", "summary.install", "decision_matrix", "winner", "caveats", "metadata.source" ], "example_final_answer": "Do not adopt run-llama/awesome-rag as a runtime. Git.Top identifies it as a curated collection with an estimated 100 items and no direct install step. For an executable local RAG project, run-llama/llama_index wins the comparison and carries a 91/100 agent score and 88/100 quality score. Caveat: the collection remains useful for discovery, but its 80/100 Git.Top score is not runtime suitability and should not be compared as if it were an installable library.", "verification": { "scope": "local_d1", "verified_at": "2026-07-31", "snapshot_id": "d1:504:2026-06-20T00:00:00Z", "source": "d1" }, "next_action": "Use the collection to expand the shortlist, then evaluate LlamaIndex and other executable candidates against ingestion, retrieval, storage, and deployment requirements." } ], "examples": [ { "id": "health-gate", "endpoint": "/api/health", "command": "curl https://git.top/api/health", "trust_checks": [ "metadata.source" ] } ], "trust_policy": [ "Inspect metadata.source before citing results." ] } } } } } } }, "/api/journeys": { "get": { "summary": "Fetch Atlas exploration journeys that connect ecosystems to recommendations, graph, alternatives, compare, score, and Agent Map surfaces.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum projects per ecosystem used to build journey links", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Atlas journeys with ecosystem ids, ordered steps, ecosystem-specific comparison paths, human page links, API links, stats, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtlasJourneysResponse" } } } } } } }, "/api/search": { "get": { "summary": "Search project knowledge by query, category, deployment, difficulty, language, project type, confidence, and Cloudflare readiness; large corpora disclose bounded D1-first candidate retrieval in metadata.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Project category", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "description": "Deployment target", "schema": { "type": "string" } }, { "name": "difficulty", "in": "query", "required": false, "description": "Difficulty level", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Primary language", "schema": { "type": "string" } }, { "name": "project_kind", "in": "query", "required": false, "description": "Project type: project or collection", "schema": { "type": "string" } }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum classification confidence: low, medium, or high", "schema": { "type": "string" } }, { "name": "cloudflare_ready", "in": "query", "required": false, "description": "Boolean Cloudflare readiness filter", "schema": { "type": "string" } }, { "name": "ranking", "in": "query", "required": false, "description": "Use browse for broad category/deployment discovery", "schema": { "type": "string" } }, { "name": "profile", "in": "query", "required": false, "description": "Response profile: full (default), compact, decision, or evidence. Compact profiles omit raw knowledge rows.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor bound to this query and corpus snapshot", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project search results with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "profile": "full", "query": { "q": "cloudflare agent framework", "limit": 3, "require_d1": true }, "search": { "applied_filters": { "q": "cloudflare agent framework" }, "known_filter_values": { "project_kind": [ "project", "collection" ], "min_confidence": [ "low", "medium", "high" ] } }, "projects": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" } ], "page": { "offset": 0, "limit": 3, "has_more": true, "next_cursor": "eyJ2IjoxLCJzIjoiZDE6NTAwOnNuYXBzaG90IiwicSI6InF1ZXJ5IiwibyI6M30", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z" }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1", "candidate_retrieval": "d1_first", "candidate_count": 42, "candidate_limit": 1000, "loaded_project_limit": 1000, "truncated": false } } } } } } } }, "/api/project/{owner}/{repo}": { "get": { "summary": "Fetch a project knowledge record with agent summary, related projects, scores, and metadata.", "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "GitHub owner", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "GitHub repository name", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project knowledge view plus summary, full knowledge, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "example": { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "summary": { "tl_dr": "Cloudflare Workers-native agent runtime.", "purpose": "Build stateful tool-using agents on Cloudflare infrastructure.", "install": "Follow the repository README for package setup.", "inputs": [ "task prompt", "tools", "state" ], "outputs": [ "agent runs", "tool calls" ], "good_for": [ "Cloudflare-native agents" ], "not_good_for": [ "Python-only local stacks" ], "deployment": [ "cloudflare" ], "alternatives": [ { "repo": "langchain-ai/langgraph", "reason": "Broader graph workflow ecosystem." } ] }, "project": { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" }, "knowledge": { "project": { "full_name": "cloudflare/agents" } }, "related": [ { "repo": "cloudflare/workers-sdk", "reason": "Shared Cloudflare deployment target." } ], "classification": { "category": { "value": "agent_framework", "confidence": "high", "evidence": [ "Repository topics and README mention agents." ] } }, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "classification": { "category": { "value": "agent_framework", "confidence": "high", "evidence": [ "Repository topics and README mention agents." ] } }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "source_fields": [ "project.description", "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Classification evidence and quality signals are usable for shortlist reasoning.", "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Classification evidence and quality signals are usable for shortlist reasoning.", "source_fields": [ "project.description", "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/project/{project}": { "get": { "summary": "Fetch a project knowledge record with agent summary by short slug, encoded owner/repo, or Git.Top product alias.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project slug, encoded owner/repo id, or product alias such as claude-code", "schema": { "type": "string" } }, { "name": "related_limit", "in": "query", "required": false, "description": "Maximum related project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project knowledge view plus summary, full knowledge, related projects, resolved_from, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/project": { "post": { "summary": "Fetch a project knowledge record with agent summary from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLookupRequest" } } } }, "responses": { "200": { "description": "Project knowledge view plus summary, full knowledge, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "400": { "description": "Invalid project lookup request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects": { "get": { "summary": "Fetch up to 20 canonical projects in one snapshot-consistent response.", "parameters": [ { "name": "ids", "in": "query", "required": false, "description": "Comma-separated canonical owner/repo identifiers", "schema": { "type": "string" } }, { "name": "profile", "in": "query", "required": false, "description": "Response profile: compact, decision, or evidence", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch project response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsBatchResponse" } } } }, "400": { "description": "Invalid batch request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Fetch up to 20 canonical projects from a structured request using one corpus snapshot.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsBatchRequest" } } } }, "responses": { "200": { "description": "Batch project response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsBatchResponse" } } } }, "400": { "description": "Invalid batch request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/changes": { "get": { "summary": "Read D1 project changes with cursor pagination and deletion tombstones.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from a previous response", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Optional ISO-8601 lower bound", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size from 1 to 100", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project change feed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectChangesResponse" } } } }, "400": { "description": "Invalid cursor, timestamp, or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/feedback/proposals": { "post": { "summary": "Validate a structured agent correction proposal; persist only with FEEDBACK_SECRET authorization.", "security": [ {}, { "feedbackSecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackProposalRequest" } } } }, "responses": { "200": { "description": "Validated proposal that was not persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackProposalResponse" } } } }, "202": { "description": "Authenticated proposal persisted for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackProposalResponse" } } } }, "400": { "description": "Invalid proposal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Invalid feedback authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/trending": { "get": { "summary": "List trending projects from the loaded knowledge set.", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Optional category filter", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor bound to this query and corpus snapshot", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trending projects with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendingResponse" }, "example": { "projects": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" } ], "page": { "offset": 0, "limit": 3, "has_more": true, "next_cursor": "eyJ2IjoxLCJzIjoiZDE6NTAwOnNuYXBzaG90IiwicSI6InF1ZXJ5IiwibyI6M30", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z" }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/category/{category}": { "get": { "summary": "List projects in a category with snapshot-bound cursor pagination.", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Git.Top project category", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor bound to this category and corpus snapshot", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category knowledge rows with pagination and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResponse" } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Cursor snapshot is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/trends": { "get": { "summary": "Inspect corpus-level open-source trends by category, deployment, language, and project momentum.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum bucket and project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trend summary with stats, trend_signals, buckets, rising_projects, agent_briefing, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendsResponse" }, "example": { "summary": "Agent frameworks and MCP projects are leading current corpus demand.", "stats": { "project_count": 500, "category_count": 14 }, "trend_signals": [ { "label": "Cloudflare-ready agents", "strength": "high" } ], "categories": [ { "category": "agent_framework", "count": 48 } ], "deployments": [ { "deployment": "cloudflare", "count": 36 } ], "languages": [ { "language": "TypeScript", "count": 120 } ], "rising_projects": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" } ], "agent_briefing": [ "Use Trust Gate before high-confidence recommendations." ], "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/recommend": { "get": { "summary": "Recommend projects for an agent use case and constraints.", "parameters": [ { "name": "use_case", "in": "query", "required": false, "description": "Use case text", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "description": "Deployment target", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Project category", "schema": { "type": "string" } }, { "name": "license", "in": "query", "required": false, "description": "License SPDX id or license text", "schema": { "type": "string" } }, { "name": "difficulty", "in": "query", "required": false, "description": "Difficulty level", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Primary language", "schema": { "type": "string" } }, { "name": "cloudflare_ready", "in": "query", "required": false, "description": "Boolean Cloudflare readiness filter", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recommendations with fit profiles, adoption plans, risk flags, reasons, and tradeoffs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationResponse" } } } } } }, "post": { "summary": "Recommend projects from a structured JSON body with optional nested constraints.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationRequest" } } } }, "responses": { "200": { "description": "Recommendations with fit profiles, adoption plans, risk flags, constraints, ranking signals, and tradeoffs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationResponse" }, "example": { "query": { "use_case": "build Cloudflare-ready agent workflows", "deployment": "cloudflare", "category": "agent_framework", "limit": 3 }, "recommendations": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "recommendation.ranking_signals", "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "High confidence because deployment and category constraints match.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "High confidence because deployment and category constraints match.", "source_fields": [ "recommendation.ranking_signals", "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "decision_summary": "Best first pick for Cloudflare Workers-native agent workflows.", "reasons": [ "Matches deployment=cloudflare", "Agent framework category match" ], "tradeoffs": [ "Less suitable for Python-only local stacks" ], "fit_profile": { "primary_fit": "Cloudflare-native agent runtime" }, "adoption_plan": [ "Inspect project", "Check score", "Compare alternatives" ], "risk_flags": [], "matched_constraints": { "deployment": "cloudflare", "category": "agent_framework" }, "unmatched_constraints": [], "ranking_signals": { "use_case_match": 0.92, "deployment_fit": 1 }, "confidence": "high", "next_actions": [ { "label": "Inspect graph", "href": "/api/graph/cloudflare/agents", "kind": "graph" } ] } ], "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } }, "400": { "description": "Invalid recommendation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/workflow": { "get": { "summary": "Return an agent selection workflow across trends, recommendations, graph, alternatives, score, compare, and trust checks.", "parameters": [ { "name": "intent", "in": "query", "required": false, "description": "Natural-language selection goal", "schema": { "type": "string" } }, { "name": "use_case", "in": "query", "required": false, "description": "Concrete project use case", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Optional focus project or Git.Top product alias", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "description": "Deployment target", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Project category", "schema": { "type": "string" } }, { "name": "license", "in": "query", "required": false, "description": "License SPDX id or license text", "schema": { "type": "string" } }, { "name": "difficulty", "in": "query", "required": false, "description": "Difficulty level", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Primary language", "schema": { "type": "string" } }, { "name": "cloudflare_ready", "in": "query", "required": false, "description": "Boolean Cloudflare readiness filter", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum recommendation count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guided workflow with recommended_sequence, shortlist, trend_context, agent_map, trust_policy, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" }, "example": { "input": { "intent": "choose a Cloudflare-ready agent framework", "constraints": { "deployment": "cloudflare", "category": "agent_framework" } }, "recommended_sequence": [ { "step": 1, "label": "Trust preflight", "url": "/api/trust", "method": "GET", "inspect": [ "decision", "metadata.source" ] }, { "step": 2, "label": "Recommend", "url": "/api/recommend?deployment=cloudflare&category=agent_framework", "method": "GET", "mcp_tool": "recommend_project" } ], "shortlist": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "recommendation.ranking_signals", "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "High confidence because deployment and category constraints match.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "High confidence because deployment and category constraints match.", "source_fields": [ "recommendation.ranking_signals", "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "decision_summary": "Best first pick for Cloudflare Workers-native agent workflows.", "reasons": [ "Matches deployment=cloudflare", "Agent framework category match" ], "tradeoffs": [ "Less suitable for Python-only local stacks" ], "fit_profile": { "primary_fit": "Cloudflare-native agent runtime" }, "adoption_plan": [ "Inspect project", "Check score", "Compare alternatives" ], "risk_flags": [], "matched_constraints": { "deployment": "cloudflare", "category": "agent_framework" }, "unmatched_constraints": [], "ranking_signals": { "use_case_match": 0.92, "deployment_fit": 1 }, "confidence": "high", "next_actions": [ { "label": "Inspect graph", "href": "/api/graph/cloudflare/agents", "kind": "graph" } ] } ], "trend_context": { "top_categories": [ "agent_framework", "mcp_server" ] }, "agent_map": { "short_path": [], "reference_path": [], "surfaces": [], "trust_policy": { "high_confidence_source": "metadata.source=d1" } }, "trust_policy": { "production_check": "Use require_d1=true for high-confidence recommendations." }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } }, "post": { "summary": "Return an agent selection workflow from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRequest" } } } }, "responses": { "200": { "description": "Guided workflow with recommended_sequence, shortlist, trend_context, agent_map, trust_policy, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "400": { "description": "Invalid workflow request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/compare": { "get": { "summary": "Compare projects by deployment, maintenance, quality, agent score, decision matrix, and next actions.", "parameters": [ { "name": "repos", "in": "query", "required": false, "description": "Comma-separated owner/repo list", "schema": { "type": "string" } }, { "name": "deployment", "in": "query", "required": false, "description": "Deployment preference", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comparison matrix with summary, stats, decision_matrix, next_actions, and winner reasoning", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" }, "example": { "requested_repos": [ "cloudflare/agents", "langchain-ai/langchain" ], "resolved_repos": [ { "requested_id": "cloudflare/agents", "resolved_id": "cloudflare/agents", "resolution": "canonical" } ], "project_ids": [ "cloudflare/agents", "langchain-ai/langchain" ], "order": "input", "context": { "deployment": "cloudflare" }, "summary": "cloudflare/agents is the strongest Cloudflare deployment fit.", "stats": { "candidate_count": 2, "highest_agent_score": 90 }, "projects": [ { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" } ], "decision_matrix": [ { "repo": "cloudflare/agents", "strengths": [ "Cloudflare-ready" ], "tradeoffs": [ "Smaller ecosystem than LangChain" ], "next_step": "Inspect graph and score evidence." } ], "winner": { "repo": "cloudflare/agents" }, "reasoning": [ "Deployment fit favors cloudflare/agents." ], "next_actions": [ { "label": "Score winner", "href": "/api/score/cloudflare/agents", "kind": "score" } ], "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } }, "post": { "summary": "Compare projects from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRequest" } } } }, "responses": { "200": { "description": "Comparison matrix with summary, stats, decision_matrix, next_actions, and winner reasoning", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } } }, "400": { "description": "Invalid compare request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/alternatives/{owner}/{repo}": { "get": { "summary": "Find alternatives for a project with summary, stats, next actions, similarity scores, and match signals.", "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "GitHub owner", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "GitHub repository name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alternative project list with summary, stats, next_actions, comparison_links, similarity scores, and match signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesResponse" }, "example": { "project": { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" }, "summary": "Alternatives for Cloudflare-native agent workflows.", "stats": { "candidate_count": 5, "average_similarity": 0.76 }, "alternatives": [ { "repo": "langchain-ai/langgraph", "reason": "Graph-based agent workflow alternative." } ], "alternative_matches": [ { "project_id": "langchain-ai/langgraph", "repo": "langchain-ai/langgraph", "name": "langgraph", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "alternative.match_signals", "alternative.similarity_score", "alternative.replacement_type" ], "caveats": [ "Compare deployment, language, and dependency fit before switching." ], "confidence_reason": "Top alternative has 81/100 similarity with same category evidence.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [ "Compare deployment, language, and dependency fit before switching." ], "confidence_reason": "Top alternative has 81/100 similarity with same category evidence.", "source_fields": [ "agent_card.classification", "alternative.match_signals", "alternative.similarity_score", "alternative.replacement_type" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "similarity_score": 0.81, "alternative_reason": "Similar agent workflow category.", "replacement_type": "same_category", "fit_summary": "Better for Python graph workflows.", "adoption_notes": [ "Compare runtime and deployment requirements." ], "replacement_risk": "medium", "match_signals": { "category_overlap": true } } ], "next_actions": [ { "label": "Compare alternatives", "href": "/api/compare?repos=cloudflare/agents,langchain-ai/langgraph", "kind": "compare" } ], "comparison_links": { "compare": "/api/compare?repos=cloudflare/agents,langchain-ai/langgraph" }, "evidence": { "source_fields": [ "agent_card.classification", "alternative.match_signals", "alternative.similarity_score", "alternative.replacement_type" ], "caveats": [ "Compare deployment, language, and dependency fit before switching." ], "confidence_reason": "Top alternative has 81/100 similarity with same category evidence.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [ "Compare deployment, language, and dependency fit before switching." ], "confidence_reason": "Top alternative has 81/100 similarity with same category evidence.", "source_fields": [ "agent_card.classification", "alternative.match_signals", "alternative.similarity_score", "alternative.replacement_type" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/alternatives/{project}": { "get": { "summary": "Find alternatives by short slug, encoded owner/repo, or Git.Top product alias.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project slug, encoded owner/repo id, or product alias such as claude-code", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alternative project list with resolved_from, summary, stats, next_actions, comparison_links, similarity scores, and match signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/alternatives": { "post": { "summary": "Find alternatives for a project from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesRequest" } } } }, "responses": { "200": { "description": "Alternative project list with summary, stats, next_actions, comparison_links, similarity scores, and match signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesResponse" } } } }, "400": { "description": "Invalid alternatives request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/related/{owner}/{repo}": { "get": { "summary": "Find related ecosystem projects connected by category, deployment, dependency, topics, or use cases.", "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "GitHub owner", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "GitHub repository name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Related project list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedResponse" } } } } } } }, "/api/related/{project}": { "get": { "summary": "Find related ecosystem projects by short slug, encoded owner/repo, or Git.Top product alias.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project slug, encoded owner/repo id, or product alias such as claude-code", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Related project list with project context, resolved_from, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/related": { "post": { "summary": "Find related ecosystem projects from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedRequest" } } } }, "responses": { "200": { "description": "Related project list with project context and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedResponse" } } } }, "400": { "description": "Invalid related projects request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/score/{owner}/{repo}": { "get": { "summary": "Explain a project's Git.Top Score with weighted dimensions, adoption guidance, risk flags, next actions, related scores, evidence, and links.", "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "GitHub owner or single-segment project alias when using /api/score/{project}", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "GitHub repository name", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project score explanation with adoption guidance, risk flags, and next actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" }, "example": { "project": { "project_id": "cloudflare/agents", "repo": "cloudflare/agents", "name": "agents", "github_url": "https://github.com/cloudflare/agents", "language": "TypeScript", "license": "MIT", "project_kind": "project", "category": [ "agent_framework" ], "description": "Build and deploy AI agents on Cloudflare Workers.", "deployments": [ "cloudflare", "serverless" ], "difficulty": "intermediate", "cloudflare_ready": true, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "evidence": { "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Evidence is usable for comparison.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z" }, "project_id": "cloudflare/agents", "score": 86, "git_top_score": 86, "quality_score": 82, "agent_score": 90, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "dimensions": [ { "key": "agent_readability", "label": "Agent Readability", "score": 92, "weight": 16, "contribution": 14.7 } ], "summary": "cloudflare/agents scores 86/100.", "adoption_guidance": "Strong candidate for shortlist inclusion.", "risk_flags": [], "score_confidence": { "level": "high", "summary": "Score evidence is strong enough for shortlist ranking.", "reasons": [ "All score evidence checks are strong." ], "evidence_checklist": [ { "signal": "Classification evidence", "status": "strong" } ], "citation_guidance": "Cite metadata.source, weakest_dimension, risk_flags, and score_confidence.level." }, "strongest_dimension": { "key": "agent_readability", "label": "Agent Readability", "score": 92 }, "weakest_dimension": { "key": "stability", "label": "Stability", "score": 74 }, "evidence": { "deployments": [ "cloudflare" ], "quality_signal_confidence": { "stars_30d_delta": "snapshot", "commits_30d": "complete", "releases_180d": "partial", "contributors_90d": "complete" }, "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "caveats": [], "confidence_reason": "Score evidence is strong enough for shortlist ranking.", "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "Score evidence is strong enough for shortlist ranking.", "source_fields": [ "agent_card.classification", "metrics", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "links": { "compare_api": "/api/compare?repos=cloudflare/agents" }, "next_actions": [ { "label": "Compare shortlist", "href": "/api/compare?repos=cloudflare/agents", "kind": "compare" } ], "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/score/{project}": { "get": { "summary": "Explain a project's Git.Top Score by short slug, encoded owner/repo, or Git.Top product alias.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project slug, encoded owner/repo id, or product alias such as claude-code", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project score explanation with resolved_from, dimensions, adoption guidance, risk flags, next actions, evidence, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/score": { "post": { "summary": "Explain a project's Git.Top Score from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } } }, "responses": { "200": { "description": "Project score explanation with dimensions, adoption guidance, risk flags, verification, next actions, evidence, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Invalid score request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/graph": { "get": { "summary": "Return project relationship graph nodes, edges, stats, summary, next actions, project context, relationship groups, and migration paths.", "parameters": [ { "name": "repo", "in": "query", "required": false, "description": "Optional focus repository or Git.Top product alias such as claude-code", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge graph with graph_stats, summary, next_actions, migration_paths, alternatives, related projects, dependencies, deployment targets, and use cases when focused on a project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" }, "example": { "focus": "cloudflare/agents", "project": { "repo": "cloudflare/agents", "name": "agents", "description": "Build AI agents on Cloudflare.", "maintainer": "cloudflare", "license": "MIT", "language": "TypeScript", "recent_activity": "fresh" }, "summary": "Focused graph for cloudflare/agents.", "graph_stats": { "node_count": 4, "edge_count": 3, "relationship_counts": { "related": 1, "deployment": 1, "category": 1 } }, "relationship_groups": { "alternatives": [ { "repo": "langchain-ai/langgraph", "reason": "Agent workflow alternative." } ], "related": [ { "repo": "cloudflare/workers-sdk", "reason": "Shared deployment target." } ], "dependencies": [ "workers" ], "deployment_targets": [ "cloudflare" ], "use_cases": [ "stateful agents" ] }, "migration_paths": [ { "from": "cloudflare/agents", "to": "langchain-ai/langgraph", "compatibility": "medium", "estimated_cost": "medium", "shared_signals": [ "category:agent_framework", "use_case:stateful agents" ], "gaps": [ "Deployment targets and primary language require review." ], "validation_steps": [ "Compare API, configuration, license, and dependency requirements.", "Run the target project's minimal example or test suite." ], "evidence": [ "agent_card.category", "agent_card.deployment", "agent_card.use_cases", "project.language", "project.license" ] } ], "nodes": [ { "id": "cloudflare/agents", "label": "agents", "kind": "project", "repo": "cloudflare/agents", "score": 90 }, { "id": "deployment:cloudflare", "label": "cloudflare", "kind": "deployment" } ], "edges": [ { "source": "cloudflare/agents", "target": "deployment:cloudflare", "kind": "deployment", "weight": 96 } ], "evidence": { "source_fields": [ "agent_card.classification", "graph.nodes", "graph.edges", "graph.relationship_groups", "graph.migration_paths", "verification.signals" ], "caveats": [], "confidence_reason": "cloudflare/agents graph is grounded in indexed alternatives, related projects, deployments, dependencies, and use cases.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "cloudflare/agents graph is grounded in indexed alternatives, related projects, deployments, dependencies, and use cases.", "source_fields": [ "agent_card.classification", "graph.nodes", "graph.edges", "graph.relationship_groups", "graph.migration_paths", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } }, "post": { "summary": "Return a project relationship graph from a structured JSON body.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRequest" } } } }, "responses": { "200": { "description": "Knowledge graph with project context, graph_stats, summary, next_actions, relationship groups, and heuristic migration paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" } } } }, "400": { "description": "Invalid graph request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/atlas": { "get": { "summary": "List Atlas ecosystem maps with stats, exploration paths, comparison paths, concept/project nodes, edges, representative projects, and Agent API links.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum projects per ecosystem", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Atlas ecosystem list with stats, exploration_paths, recommendation links, map.nodes, and map.edges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtlasResponse" } } } } } } }, "/api/atlas/{ecosystem}": { "get": { "summary": "Fetch one Atlas ecosystem map with stats, exploration paths, comparison paths, concept/project nodes, edges, representative projects, and Agent API links.", "parameters": [ { "name": "ecosystem", "in": "path", "required": true, "description": "Atlas ecosystem id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Atlas ecosystem with stats, exploration_paths, recommendation links, map.nodes, and map.edges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AtlasResponse" } } } }, "404": { "description": "Atlas ecosystem not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/graph/{owner}/{repo}": { "get": { "summary": "Return project relationship graph nodes, edges, stats, summary, next actions, project context, relationship groups, and migration paths for one project.", "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "GitHub owner or single-segment project alias when using /api/graph/{project}", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "GitHub repository name", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Focused project knowledge graph with graph_stats, summary, next_actions, grouped alternatives, heuristic migration paths, related projects, dependencies, deployment targets, and use cases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" } } } } } } }, "/api/graph/{project}": { "get": { "summary": "Return a focused project relationship graph by short slug, encoded owner/repo, or Git.Top product alias, including heuristic migration paths.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project slug, encoded owner/repo id, or product alias such as claude-code", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum project count", "schema": { "type": "string" } }, { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Focused project knowledge graph with resolved_from, graph_stats, summary, next_actions, grouped alternatives, heuristic migration paths, related projects, dependencies, deployment targets, and use cases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/quality": { "get": { "summary": "Inspect release score, data trust score, confidence, coverage, and risk.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quality report with backward-compatible score, release_score, data_trust_score, score_summary, coverage, and risk fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityReportResponse" } } } } } } }, "/api/quality/review": { "get": { "summary": "Inspect low-confidence classification and collection review queue.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Low-confidence classification and collection review queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityReviewResponse" }, "example": { "project_count": 500, "review_count": 12, "low_signal_count": 18, "medium_signal_count": 24, "category_counts": { "agent_framework": 3 }, "items": [ { "project_id": "cloudflare/agents", "category": "agent_framework", "impact_score": 88, "suggested_action": "Review classification evidence." } ], "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/benchmark": { "get": { "summary": "Inspect public recommendation, explanation, data trust, review queue, and limitation benchmark metrics.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public trust benchmark summary with eval health, explanation coverage, data coverage, review queue, and known limitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkResponse" }, "example": { "name": "Git.Top Public Trust Benchmark", "positioning": "The Knowledge Graph of Open Source", "summary": "Recommendation eval top-3 hit rate is 1; explanation checks are 14/14; data trust is 82/100 with 12 review queue items.", "generated_at": "2026-07-04T00:00:00.000Z", "evaluation": { "generated_at": "2026-06-30T00:08:13.734Z", "evaluated_cases": 28, "top1_hit_rate": 0.929, "top3_hit_rate": 1, "category_accuracy": 1, "deployment_accuracy": 1, "cloudflare_readiness_accuracy": 1, "unacceptable_hit_count": 0, "review_focus": [ { "id": "search-coding-agent", "issue": "top-1 miss", "expected": [ "openai/codex" ], "observed": [ "smol-ai/developer" ] } ], "source_report": "docs/EVAL_QUALITY.md" }, "explanations": { "generated_at": "2026-07-04T02:51:39.580Z", "checks": 14, "passed": 14, "failed": 0, "coverage": 1, "source_report": "docs/EVAL_EXPLANATIONS.md" }, "data_coverage": { "project_count": 500, "category_coverage": "14/14", "low_confidence_classification_rate": 0.04, "data_trust_score": 82, "release_score": 96, "risk_level": "low" }, "review_queue": { "review_count": 12, "low_signal_count": 18, "top_impact_score": 88, "top_items": [ { "project_id": "cloudflare/agents", "category": "agent_framework", "impact_score": 88 } ] }, "known_limitations": [ "Eval quality is a CI-safe baseline over curated cases and generated fixtures." ], "recommended_use": [ "Use top_3_hit_rate, explanation coverage, data_trust_score, and review_queue before high-confidence production recommendations." ], "links": { "html": "/benchmark", "api": "/api/benchmark", "quality": "/api/quality", "review": "/api/quality/review", "trust": "/api/trust" }, "metadata": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } }, "/api/sync/status": { "get": { "summary": "Inspect sync cursor progress, freshness, health, and recent failures.", "parameters": [ { "name": "detail", "in": "query", "required": false, "description": "Response detail level: summary (default) returns five queue items; full returns up to fifty", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStatusResponse" } } } } } } }, "/api/governance/summary": { "get": { "summary": "Inspect automated operations and data-governance run summary.", "responses": { "200": { "description": "Governance run summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceSummaryResponse" } } } } } } }, "/api/governance/runs": { "get": { "summary": "List recent automated operations and data-governance runs.", "parameters": [ { "name": "task", "in": "query", "required": false, "description": "Optional governance task identifier", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum run count", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Governance run history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceRunsResponse" } } } } } } }, "/api/schema/project.v2": { "get": { "summary": "Fetch the compact project response JSON Schema.", "responses": { "200": { "description": "Project schema" } } } }, "/api/grp/query": { "post": { "summary": "Run Graph Reasoning Protocol over the knowledge graph.", "parameters": [ { "name": "require_d1", "in": "query", "required": false, "description": "Fail closed unless D1-backed data is available", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrpRequest" } } } }, "responses": { "200": { "description": "Graph-grounded project set, plan, comparison, or stack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrpResponse" }, "example": { "intent": "find a Cloudflare-ready agent framework", "mode": "find", "result_type": "project_set", "sub_goals": [ "cloudflare", "agent framework" ], "nodes": [ { "id": "cloudflare/agents", "label": "agents", "kind": "project", "score": { "final_score": 92 }, "reasons": [ "Matches Cloudflare deployment." ] } ], "edges": [ { "source": "cloudflare/agents", "target": "deployment:cloudflare", "kind": "deployment", "weight": 92, "reason": "Deployment compatibility." } ], "solution_paths": [], "recommended_stack": [], "alternatives": [], "explanation": [ "GRP interpreted the goal as find a Cloudflare-ready agent framework." ], "evidence": { "source_fields": [ "grp.request", "grp.decomposition", "grp.seeds", "grp.nodes", "grp.edges", "grp.solution_paths", "grp.recommended_stack", "verification.signals" ], "caveats": [], "confidence_reason": "GRP result is grounded in retrieved seed projects, graph nodes, and relationship or path evidence.", "verification": { "schema_version": "git-top.verification.v1", "overall_status": "partial", "observed_at": "2026-07-04T00:00:00.000Z", "signals": { "activity": { "status": "observed", "source": "github_metadata", "evidence": [ "project.pushed_at", "metrics.recent_push_days" ] }, "license": { "status": "observed", "source": "github_metadata", "evidence": [ "project.license" ] }, "documentation": { "status": "observed", "source": "github_metadata", "evidence": [ "project.description" ] }, "runtime": { "status": "inferred", "source": "git_top_heuristic", "evidence": [ "agent_card.deployment", "agent_card.cloudflare_ready" ] }, "install": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "installation/build probe is not enabled" ] }, "security": { "status": "not_run", "source": "git_top_runtime", "evidence": [ "dependency/security scan is not enabled" ] }, "mcp": { "status": "not_applicable", "source": "git_top_runtime", "evidence": [ "project is not classified as mcp_server" ] } }, "coverage": { "observed": 3, "inferred": 1, "not_run": 2, "unknown": 0 }, "next_steps": [ "Run an installation/build probe before production adoption.", "Run a dependency and security scan before treating the score as a trust claim." ] }, "last_verified_at": "2026-07-04T00:00:00.000Z" }, "caveats": [], "confidence_reason": "GRP result is grounded in retrieved seed projects, graph nodes, and relationship or path evidence.", "source_fields": [ "grp.request", "grp.decomposition", "grp.seeds", "grp.nodes", "grp.edges", "grp.solution_paths", "grp.recommended_stack", "verification.signals" ], "last_verified_at": "2026-07-04T00:00:00.000Z", "metadata": { "version": "grp.v1", "generated_at": "2026-07-04T00:00:00.000Z", "candidate_count": 1, "max_depth": 2, "data_source": { "source": "d1", "reason": "d1_query", "project_count": 500, "generated_at": "2026-07-04T00:00:00.000Z", "snapshot_id": "d1:500:2026-07-04T00:00:00.000Z", "latest_synced_at": "2026-07-04T00:00:00.000Z", "schema_version": "git-top.knowledge.v1" } } } } } } } } }, "/api/admin/alternatives": { "post": { "summary": "Refresh generated alternatives for the full corpus or a bounded batch.", "security": [ { "syncSecret": [] } ], "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Zero-based project offset for a bounded refresh", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Batch size from 1 to 25; omit only for small-corpus full refreshes", "schema": { "type": "string" } }, { "name": "record_run", "in": "query", "required": false, "description": "Whether to record the derived:alternatives governance run", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alternatives refresh result and optional governance run" }, "400": { "description": "Invalid offset, limit, or record_run parameter" }, "401": { "description": "Missing or invalid admin authorization" }, "405": { "description": "Alternatives refresh requires POST" } } } }, "/api/admin/alternatives/progress": { "post": { "summary": "Advance the persisted alternatives refresh cursor by one bounded batch.", "security": [ { "syncSecret": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Batch size from 1 to 25", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Incremental alternatives refresh result and persisted cursor progress" }, "400": { "description": "Invalid limit parameter" }, "401": { "description": "Missing or invalid admin authorization" }, "405": { "description": "Alternatives progress requires POST" } } } }, "/api/admin/discovery": { "post": { "summary": "Discover and sync new candidate repositories from GitHub search.", "security": [ { "syncSecret": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_candidates": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Maximum number of new candidates to sync in this run." }, "search_index": { "type": "integer", "description": "Optional deterministic index for the rotating discovery query." } } } } } }, "responses": { "200": { "description": "Candidate discovery result and recorded governance run" }, "401": { "description": "Missing or invalid admin authorization" }, "405": { "description": "Candidate discovery requires POST" } } } }, "/api/admin/classification-overrides": { "get": { "summary": "List reviewed classification overrides.", "security": [ { "syncSecret": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum override count", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reviewed classification override ledger" }, "401": { "description": "Missing or invalid admin authorization" } } }, "post": { "summary": "Create or update a reviewed classification override.", "security": [ { "syncSecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationOverrideInput" } } } }, "responses": { "200": { "description": "Persisted classification override" }, "400": { "description": "Invalid classification override payload" }, "401": { "description": "Missing or invalid admin authorization" } } } }, "/api/admin/governance/runs": { "post": { "summary": "Record an automated governance run result.", "security": [ { "syncSecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceRunInput" } } } }, "responses": { "200": { "description": "Persisted governance run" }, "400": { "description": "Invalid governance run payload" }, "401": { "description": "Missing or invalid admin authorization" } } } }, "/mcp": { "get": { "summary": "Discover Git.Top MCP tools, docs, quickstart, and JSON-RPC examples.", "responses": { "200": { "description": "MCP discovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDiscoveryResponse" }, "example": { "endpoint": "https://git.top/mcp", "docs_url": "https://git.top/docs", "schema_url": "https://git.top/api/schema/project.v2", "health_url": "https://git.top/api/health", "quality_url": "https://git.top/api/quality", "agent_map_url": "https://git.top/api/agent-map", "quickstart": { "first_step": "Call tools/list, then use require_d1 for high-confidence reads." }, "agent_map": { "short_path": [], "reference_path": [], "surfaces": [], "trust_policy": { "high_confidence_source": "metadata.source=d1" } }, "tools": [ { "name": "search_projects", "description": "Search Git.Top projects.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" }, "require_d1": { "type": "boolean" } } } } ] } } } } } }, "post": { "summary": "Call MCP tools/list or tools/call via JSON-RPC.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" }, "examples": { "toolsList": { "summary": "List Git.Top MCP tools", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } }, "toolCall": { "summary": "Call a Git.Top MCP tool", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_projects", "arguments": { "query": "cloudflare agent framework", "require_d1": true, "limit": 5 } } } } } } } }, "responses": { "200": { "description": "JSON-RPC success result. For tools/call, parse result.content[0].text as JSON before reading metadata or result fields; git_top_grp_query defaults to profile=compact and accepts profile=full for the complete graph.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcSuccessResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "{\"projects\":[{\"project_id\":\"cloudflare/agents\",\"repo\":\"cloudflare/agents\",\"name\":\"agents\",\"github_url\":\"https://github.com/cloudflare/agents\",\"language\":\"TypeScript\",\"license\":\"MIT\",\"project_kind\":\"project\",\"category\":[\"agent_framework\"],\"description\":\"Build and deploy AI agents on Cloudflare Workers.\",\"deployments\":[\"cloudflare\",\"serverless\"],\"difficulty\":\"intermediate\",\"cloudflare_ready\":true,\"git_top_score\":86,\"quality_score\":82,\"agent_score\":90,\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"quality_signal_confidence\":{\"stars_30d_delta\":\"snapshot\",\"commits_30d\":\"complete\",\"releases_180d\":\"partial\",\"contributors_90d\":\"complete\"},\"evidence\":{\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"},\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"}],\"metadata\":{\"source\":\"d1\",\"reason\":\"d1_query\",\"project_count\":500,\"generated_at\":\"2026-07-04T00:00:00.000Z\",\"snapshot_id\":\"d1:500:2026-07-04T00:00:00.000Z\",\"latest_synced_at\":\"2026-07-04T00:00:00.000Z\",\"schema_version\":\"git-top.knowledge.v1\"}}" } ] } } } } }, "202": { "description": "Accepted JSON-RPC notification with no response body, used for notifications/initialized." }, "400": { "description": "JSON-RPC error result for invalid JSON, unsupported methods, unknown tools, invalid arguments, strict D1 failures (-32003), stale cursors (-32004), or unresolved singular projects (-32005).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcErrorResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "error": { "code": -32005, "message": "Project missing/project was not found." } } } } } } } }, "/mcp/core": { "get": { "summary": "Discover the focused Git.Top MCP core profile for first-time agent connections.", "responses": { "200": { "description": "MCP core profile discovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDiscoveryResponse" }, "example": { "endpoint": "https://git.top/mcp/core", "docs_url": "https://git.top/docs", "schema_url": "https://git.top/api/schema/project.v2", "health_url": "https://git.top/api/health", "quality_url": "https://git.top/api/quality", "agent_map_url": "https://git.top/api/agent-map", "quickstart": { "first_step": "Call tools/list, then use require_d1 for high-confidence reads." }, "agent_map": { "short_path": [], "reference_path": [], "surfaces": [], "trust_policy": { "high_confidence_source": "metadata.source=d1" } }, "tools": [ { "name": "search_projects", "description": "Search Git.Top projects." }, { "name": "get_project", "description": "Return one structured project record." }, { "name": "recommend_project", "description": "Recommend projects for a use case and constraints." }, { "name": "compare_projects", "description": "Compare a project shortlist." }, { "name": "get_agent_workflow", "description": "Return a guided project-selection workflow." } ], "profile": "core", "profiles": { "core": { "endpoint": "https://git.top/mcp/core", "tool_count": 5 }, "full": { "endpoint": "https://git.top/mcp", "tool_count": 21 } } } } } } } }, "post": { "summary": "Call the focused MCP core profile via JSON-RPC.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "MCP core JSON-RPC success result; the full profile endpoint supports bounded compact and opt-in full GRP responses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcSuccessResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "{\"projects\":[{\"project_id\":\"cloudflare/agents\",\"repo\":\"cloudflare/agents\",\"name\":\"agents\",\"github_url\":\"https://github.com/cloudflare/agents\",\"language\":\"TypeScript\",\"license\":\"MIT\",\"project_kind\":\"project\",\"category\":[\"agent_framework\"],\"description\":\"Build and deploy AI agents on Cloudflare Workers.\",\"deployments\":[\"cloudflare\",\"serverless\"],\"difficulty\":\"intermediate\",\"cloudflare_ready\":true,\"git_top_score\":86,\"quality_score\":82,\"agent_score\":90,\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"quality_signal_confidence\":{\"stars_30d_delta\":\"snapshot\",\"commits_30d\":\"complete\",\"releases_180d\":\"partial\",\"contributors_90d\":\"complete\"},\"evidence\":{\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"},\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"}],\"metadata\":{\"source\":\"d1\",\"reason\":\"d1_query\",\"project_count\":500,\"generated_at\":\"2026-07-04T00:00:00.000Z\",\"snapshot_id\":\"d1:500:2026-07-04T00:00:00.000Z\",\"latest_synced_at\":\"2026-07-04T00:00:00.000Z\",\"schema_version\":\"git-top.knowledge.v1\"}}" } ] } } } } }, "202": { "description": "Accepted JSON-RPC notification with no response body." }, "400": { "description": "MCP core JSON-RPC error result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcErrorResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "error": { "code": -32005, "message": "Project missing/project was not found." } } } } } } } }, "/mcp/core/source/{source}": { "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Normalized campaign source preserved when an MCP client removes query parameters", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,47}$" } } ], "get": { "summary": "Discover the focused Git.Top MCP core profile while preserving campaign attribution.", "responses": { "200": { "description": "Attributed MCP core profile discovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpDiscoveryResponse" }, "example": { "endpoint": "https://git.top/mcp/core/source/smithery", "docs_url": "https://git.top/docs", "schema_url": "https://git.top/api/schema/project.v2", "health_url": "https://git.top/api/health", "quality_url": "https://git.top/api/quality", "agent_map_url": "https://git.top/api/agent-map", "quickstart": { "first_step": "Call tools/list, then use require_d1 for high-confidence reads." }, "agent_map": { "short_path": [], "reference_path": [], "surfaces": [], "trust_policy": { "high_confidence_source": "metadata.source=d1" } }, "tools": [ { "name": "search_projects", "description": "Search Git.Top projects." }, { "name": "get_project", "description": "Return one structured project record." }, { "name": "recommend_project", "description": "Recommend projects for a use case and constraints." }, { "name": "compare_projects", "description": "Compare a project shortlist." }, { "name": "get_agent_workflow", "description": "Return a guided project-selection workflow." } ], "profile": "core", "profiles": { "core": { "endpoint": "https://git.top/mcp/core", "tool_count": 5 }, "full": { "endpoint": "https://git.top/mcp", "tool_count": 21 } } } } } } } }, "post": { "summary": "Call the focused MCP core profile via an attributed JSON-RPC endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "Attributed MCP core JSON-RPC success result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcSuccessResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "{\"projects\":[{\"project_id\":\"cloudflare/agents\",\"repo\":\"cloudflare/agents\",\"name\":\"agents\",\"github_url\":\"https://github.com/cloudflare/agents\",\"language\":\"TypeScript\",\"license\":\"MIT\",\"project_kind\":\"project\",\"category\":[\"agent_framework\"],\"description\":\"Build and deploy AI agents on Cloudflare Workers.\",\"deployments\":[\"cloudflare\",\"serverless\"],\"difficulty\":\"intermediate\",\"cloudflare_ready\":true,\"git_top_score\":86,\"quality_score\":82,\"agent_score\":90,\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"quality_signal_confidence\":{\"stars_30d_delta\":\"snapshot\",\"commits_30d\":\"complete\",\"releases_180d\":\"partial\",\"contributors_90d\":\"complete\"},\"evidence\":{\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"verification\":{\"schema_version\":\"git-top.verification.v1\",\"overall_status\":\"partial\",\"observed_at\":\"2026-07-04T00:00:00.000Z\",\"signals\":{\"activity\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.pushed_at\",\"metrics.recent_push_days\"]},\"license\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.license\"]},\"documentation\":{\"status\":\"observed\",\"source\":\"github_metadata\",\"evidence\":[\"project.description\"]},\"runtime\":{\"status\":\"inferred\",\"source\":\"git_top_heuristic\",\"evidence\":[\"agent_card.deployment\",\"agent_card.cloudflare_ready\"]},\"install\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"installation/build probe is not enabled\"]},\"security\":{\"status\":\"not_run\",\"source\":\"git_top_runtime\",\"evidence\":[\"dependency/security scan is not enabled\"]},\"mcp\":{\"status\":\"not_applicable\",\"source\":\"git_top_runtime\",\"evidence\":[\"project is not classified as mcp_server\"]}},\"coverage\":{\"observed\":3,\"inferred\":1,\"not_run\":2,\"unknown\":0},\"next_steps\":[\"Run an installation/build probe before production adoption.\",\"Run a dependency and security scan before treating the score as a trust claim.\"]},\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"},\"caveats\":[],\"confidence_reason\":\"Evidence is usable for comparison.\",\"source_fields\":[\"agent_card.classification\",\"metrics\",\"verification.signals\"],\"last_verified_at\":\"2026-07-04T00:00:00.000Z\"}],\"metadata\":{\"source\":\"d1\",\"reason\":\"d1_query\",\"project_count\":500,\"generated_at\":\"2026-07-04T00:00:00.000Z\",\"snapshot_id\":\"d1:500:2026-07-04T00:00:00.000Z\",\"latest_synced_at\":\"2026-07-04T00:00:00.000Z\",\"schema_version\":\"git-top.knowledge.v1\"}}" } ] } } } } }, "202": { "description": "Accepted JSON-RPC notification with no response body." }, "400": { "description": "Attributed MCP core JSON-RPC error result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcErrorResponse" }, "example": { "jsonrpc": "2.0", "id": 2, "error": { "code": -32005, "message": "Project missing/project was not found." } } } } } } } } }, "components": { "securitySchemes": { "syncSecret": { "type": "http", "scheme": "bearer", "description": "Admin endpoints require the SYNC_SECRET bearer token." }, "feedbackSecret": { "type": "http", "scheme": "bearer", "description": "Optional FEEDBACK_SECRET. Without it, proposals are validated and fingerprinted but not persisted." } }, "schemas": { "Metadata": { "type": "object", "description": "Common provenance envelope for agent-facing responses. Agents should require source=d1 for high-confidence production claims and disclose seed fallback.", "properties": { "source": { "type": "string", "enum": [ "d1", "seed" ] }, "reason": { "type": "string" }, "project_count": { "type": "integer" }, "generated_at": { "type": "string", "format": "date-time" }, "snapshot_id": { "type": "string", "description": "Stable identity for the corpus snapshot used by this response." }, "latest_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "schema_version": { "type": "string", "enum": [ "git-top.knowledge.v1" ] }, "loaded_project_limit": { "type": "integer", "description": "Maximum D1 knowledge or search-candidate rows loaded into the bounded ranking set when present." }, "truncated": { "type": "boolean", "description": "Whether the D1-backed ranking or candidate set reached its limit and may omit additional matching rows." }, "candidate_retrieval": { "type": "string", "enum": [ "d1_first" ], "description": "Search-only marker indicating that deterministic filters and broad query matching ran in D1 before TypeScript ranking." }, "candidate_count": { "type": "integer", "description": "Number of D1 search candidates passed to the authoritative TypeScript filter and ranking stage." }, "candidate_limit": { "type": "integer", "description": "Maximum number of D1 search candidates passed to the ranking stage." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Fallback, count, freshness, or trust caveats that agents should account for before citing results." } } }, "ErrorResponse": { "type": "object", "description": "Common API error envelope.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable error code when available, such as d1_required." }, "message": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "HealthResponse": { "type": "object", "description": "Health and source-preflight response. Agents should inspect db, metadata.source, sync_freshness, and project counts before trusting recommendations.", "required": [ "ok", "db", "project_count", "raw_project_count", "knowledge_ready_project_count", "sync_health", "sync_freshness", "metadata" ], "properties": { "ok": { "type": "boolean" }, "db": { "type": "string", "enum": [ "available", "missing", "error" ] }, "project_count": { "type": "integer" }, "raw_project_count": { "type": "integer" }, "knowledge_ready_project_count": { "type": "integer" }, "sync_health": { "type": "string" }, "sync_freshness": { "type": "string" }, "last_successful_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "hours_since_successful_sync": { "type": [ "number", "null" ] }, "operational_storage": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "warning", "critical", "unknown" ] }, "github_cache_entries": { "type": "integer" }, "github_cache_body_bytes": { "type": "integer" }, "github_cache_max_entries": { "type": "integer" }, "github_cache_retention_entries": { "type": "integer" }, "github_cache_body_budget_bytes": { "type": "integer" }, "utilization": { "type": "number" }, "star_snapshot_count": { "type": "integer" }, "sync_run_count": { "type": "integer" }, "governance_run_count": { "type": "integer" }, "project_change_count": { "type": "integer" }, "feedback_proposal_count": { "type": "integer" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "TrustGateResponse": { "type": "object", "description": "Production-readiness gate for high-confidence agent recommendations.", "required": [ "detail", "decision", "production_ready", "freshness_slo", "checks", "required_for_high_confidence", "agent_policy", "health", "sync", "quality", "metadata" ], "properties": { "name": { "type": "string" }, "positioning": { "type": "string" }, "detail": { "type": "string", "enum": [ "summary", "full" ] }, "decision": { "type": "string", "enum": [ "allow", "caution", "block" ] }, "summary": { "type": "string" }, "production_ready": { "type": "boolean" }, "freshness_slo": { "oneOf": [ { "$ref": "#/components/schemas/SyncFreshnessSlo" }, { "type": "null" } ], "description": "Separately reports hot-project freshness and whole-corpus freshness against each tier's selected window." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/TrustGateCheck" } }, "required_for_high_confidence": { "type": "array", "items": { "type": "string" } }, "agent_policy": { "$ref": "#/components/schemas/TrustGateAgentPolicy" }, "health": { "$ref": "#/components/schemas/HealthResponse" }, "sync": { "type": "object", "additionalProperties": true }, "quality": { "$ref": "#/components/schemas/QualityReportResponse" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "TrustGateCheck": { "type": "object", "required": [ "id", "label", "status", "observed", "requirement" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "observed": { "type": "string" }, "requirement": { "type": "string" } } }, "TrustGateAgentPolicy": { "type": "object", "properties": { "high_confidence_use": { "type": "string" }, "caution_use": { "type": "string" }, "block_use": { "type": "string" }, "cite": { "type": "array", "items": { "type": "string" } }, "disclose_when": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "VerificationSignal": { "type": "object", "description": "One project verification signal. observed and inferred are indexed evidence; not_run means the independent probe has not been executed.", "required": [ "status", "source", "evidence" ], "properties": { "status": { "type": "string", "enum": [ "verified", "observed", "inferred", "not_run", "not_applicable", "unknown" ] }, "source": { "type": "string", "enum": [ "github_metadata", "git_top_heuristic", "git_top_runtime" ] }, "evidence": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "VerificationPackage": { "type": "object", "description": "Structured verification coverage for project selection. It does not claim install, security, runtime, or MCP execution unless a signal is verified.", "required": [ "schema_version", "overall_status", "observed_at", "signals", "coverage", "next_steps" ], "properties": { "schema_version": { "type": "string", "const": "git-top.verification.v1" }, "overall_status": { "type": "string", "enum": [ "complete", "partial", "unverified" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "signals": { "type": "object", "required": [ "activity", "license", "documentation", "runtime", "install", "security", "mcp" ], "properties": { "activity": { "$ref": "#/components/schemas/VerificationSignal" }, "license": { "$ref": "#/components/schemas/VerificationSignal" }, "documentation": { "$ref": "#/components/schemas/VerificationSignal" }, "runtime": { "$ref": "#/components/schemas/VerificationSignal" }, "install": { "$ref": "#/components/schemas/VerificationSignal" }, "security": { "$ref": "#/components/schemas/VerificationSignal" }, "mcp": { "$ref": "#/components/schemas/VerificationSignal" } }, "additionalProperties": false }, "coverage": { "type": "object", "required": [ "observed", "inferred", "not_run", "unknown" ], "properties": { "observed": { "type": "integer", "minimum": 0 }, "inferred": { "type": "integer", "minimum": 0 }, "not_run": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "next_steps": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "ProjectCard": { "type": "object", "description": "Compact project card used in search, recommendations, comparison, alternatives, and related project lists.", "required": [ "project_id", "repo", "name" ], "properties": { "project_id": { "type": "string" }, "repo": { "type": "string" }, "name": { "type": "string" }, "github_url": { "type": "string" }, "homepage_url": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "license": { "type": [ "string", "null" ] }, "project_kind": { "type": "string", "enum": [ "project", "collection" ] }, "collection_metadata": { "type": "object", "additionalProperties": true }, "category": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "overview": { "type": "string" }, "deployments": { "type": "array", "items": { "type": "string" } }, "difficulty": { "type": "string" }, "cloudflare_ready": { "type": "boolean" }, "git_top_score": { "type": "number" }, "quality_score": { "type": "number" }, "agent_score": { "type": "number" }, "score": { "type": "number" }, "classification": { "type": "object", "additionalProperties": true }, "quality_signal_confidence": { "$ref": "#/components/schemas/QualitySignalConfidence" }, "verification": { "$ref": "#/components/schemas/VerificationPackage" }, "summary": { "$ref": "#/components/schemas/ProjectSummary" }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "NormalizedEvidence": { "type": "object", "description": "Normalized evidence package for agent citation and caveat handling.", "properties": { "classification": { "type": "object", "additionalProperties": true }, "quality_signal_confidence": { "$ref": "#/components/schemas/QualitySignalConfidence" }, "verification": { "oneOf": [ { "$ref": "#/components/schemas/VerificationPackage" }, { "type": "null" } ] }, "source_fields": { "type": "array", "items": { "type": "string" } }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "QualitySignalConfidence": { "type": "object", "description": "Completeness hints for GitHub-derived score inputs. Agents should avoid overclaiming partial or unknown signals.", "properties": { "stars_30d_delta": { "type": "string", "enum": [ "snapshot", "estimated" ] }, "stars_30d_window_days": { "type": "integer" }, "commits_30d": { "type": "string", "enum": [ "complete", "partial", "unknown" ] }, "releases_180d": { "type": "string", "enum": [ "complete", "partial", "unknown" ] }, "contributors_90d": { "type": "string", "enum": [ "complete", "partial", "unknown" ] } }, "additionalProperties": true }, "SearchResponse": { "type": "object", "required": [ "profile", "query", "search", "projects", "page", "metadata" ], "properties": { "profile": { "type": "string", "enum": [ "full", "compact", "decision", "evidence" ], "default": "full" }, "query": { "type": "object", "additionalProperties": true }, "search": { "type": "object", "properties": { "applied_filters": { "type": "object", "additionalProperties": true }, "known_filter_values": { "type": "object", "additionalProperties": true }, "empty_reason": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "string" } }, "query_interpretation": { "type": "object", "properties": { "original": { "type": "string" }, "normalized": { "type": "string" }, "transformations": { "type": "array", "items": { "type": "string" } } } } }, "additionalProperties": true }, "projects": { "type": "array", "description": "Project cards shaped by profile. compact returns bounded identity, fit, score, and verification fields; full preserves the complete project card.", "items": { "type": "object", "additionalProperties": true } }, "knowledge": { "type": "array", "description": "Raw project knowledge rows retained only for the default full profile.", "items": { "type": "object", "additionalProperties": true } }, "page": { "$ref": "#/components/schemas/CursorPage" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "TrendingResponse": { "type": "object", "required": [ "projects", "page", "metadata" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCard" } }, "query": { "type": "object", "additionalProperties": true }, "page": { "$ref": "#/components/schemas/CursorPage" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "CategoryResponse": { "type": "object", "required": [ "projects", "page", "metadata" ], "properties": { "projects": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Full project knowledge rows retained for backward compatibility." }, "page": { "$ref": "#/components/schemas/CursorPage" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CursorPage": { "type": "object", "required": [ "offset", "limit", "has_more", "next_cursor", "snapshot_id" ], "properties": { "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null on the final page." }, "snapshot_id": { "type": "string", "description": "Corpus snapshot to which this page and cursor are bound." } } }, "TrendsResponse": { "type": "object", "required": [ "summary", "stats", "trend_signals", "metadata" ], "properties": { "summary": { "type": "string" }, "stats": { "type": "object", "additionalProperties": true }, "trend_signals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "deployments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "languages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "rising_projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCard" } }, "agent_briefing": { "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "ProjectResponse": { "type": "object", "description": "Full project lookup response. Agents should read summary first, then classification, quality_signal_confidence, verification, metadata, and related evidence before citing claims.", "required": [ "project_id", "repo", "summary", "knowledge", "metadata" ], "properties": { "project_id": { "type": "string" }, "repo": { "type": "string" }, "resolved_from": { "type": "object", "additionalProperties": true }, "summary": { "$ref": "#/components/schemas/ProjectSummary" }, "project": { "$ref": "#/components/schemas/ProjectCard" }, "knowledge": { "type": "object", "additionalProperties": true }, "related": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true } }, "score": { "type": "number" }, "git_top_score": { "type": "number" }, "quality_score": { "type": "number" }, "agent_score": { "type": "number" }, "classification": { "type": "object", "additionalProperties": true }, "quality_signal_confidence": { "$ref": "#/components/schemas/QualitySignalConfidence" }, "verification": { "$ref": "#/components/schemas/VerificationPackage" }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "ProjectsBatchRequest": { "type": "object", "required": [ "project_ids" ], "properties": { "project_ids": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" } }, "profile": { "type": "string", "enum": [ "compact", "decision", "evidence" ], "default": "compact" } } }, "ProjectsBatchResponse": { "type": "object", "required": [ "profile", "requested_count", "found_count", "projects", "missing", "metadata" ], "properties": { "profile": { "type": "string", "enum": [ "compact", "decision", "evidence" ] }, "requested_count": { "type": "integer" }, "found_count": { "type": "integer" }, "projects": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "missing": { "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ProjectChangesResponse": { "type": "object", "required": [ "changes", "page", "retention", "metadata" ], "properties": { "changes": { "type": "array", "items": { "type": "object", "required": [ "cursor", "project_id", "change_type", "changed_fields", "occurred_at", "tombstone" ], "properties": { "cursor": { "type": "string", "description": "Opaque cursor for this event." }, "project_id": { "type": "string" }, "change_type": { "type": "string", "enum": [ "added", "updated", "classification_changed", "score_changed", "deleted" ] }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "before": { "type": [ "object", "null" ], "additionalProperties": true }, "after": { "type": [ "object", "null" ], "additionalProperties": true }, "occurred_at": { "type": "string", "format": "date-time" }, "tombstone": { "type": "boolean" } } } }, "page": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "description": "Opaque polling cursor returned even when has_more is false." } } }, "retention": { "type": "object", "properties": { "days": { "type": "integer", "enum": [ 30 ] }, "earliest_guaranteed_at": { "type": "string", "format": "date-time" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "FeedbackProposalRequest": { "type": "object", "required": [ "project_id", "feedback_type", "proposed", "evidence", "rationale" ], "properties": { "project_id": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" }, "feedback_type": { "type": "string", "enum": [ "classification", "alternative", "metadata", "stale", "other" ] }, "proposed": { "type": "object", "minProperties": 1, "additionalProperties": true }, "evidence": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "additionalProperties": true } }, "rationale": { "type": "string", "minLength": 12, "maxLength": 2000 }, "source_agent": { "type": "string", "maxLength": 200 }, "source_url": { "type": "string", "format": "uri" } } }, "FeedbackProposalResponse": { "type": "object", "required": [ "proposal", "persisted", "review_required", "mutation_policy", "authorization" ], "properties": { "proposal": { "type": "object", "additionalProperties": true }, "persisted": { "type": "boolean" }, "review_required": { "type": "boolean", "enum": [ true ] }, "mutation_policy": { "type": "string" }, "authorization": { "type": "string" } } }, "RecommendationResponse": { "type": "object", "required": [ "query", "recommendations", "metadata" ], "properties": { "query": { "type": "object", "additionalProperties": true }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "Recommendation": { "allOf": [ { "$ref": "#/components/schemas/ProjectCard" }, { "type": "object", "properties": { "decision_summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "tradeoffs": { "type": "array", "items": { "type": "string" } }, "fit_profile": { "type": "object", "additionalProperties": true }, "adoption_plan": { "type": "array", "items": { "type": "string" } }, "risk_flags": { "type": "array", "items": { "type": "string" } }, "matched_constraints": { "type": "object", "additionalProperties": true }, "unmatched_constraints": { "type": "object", "additionalProperties": true }, "ranking_signals": { "type": "object", "additionalProperties": { "type": "number" } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "confidence_reason": { "type": "string" }, "evidence": { "allOf": [ { "$ref": "#/components/schemas/NormalizedEvidence" }, { "type": "object", "properties": { "recommendation_reasons": { "type": "array", "items": { "type": "string" } }, "ranking_signals": { "type": "object", "additionalProperties": { "type": "number" } }, "matched_constraints": { "type": "object", "additionalProperties": true }, "unmatched_constraints": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } ] }, "caveats": { "type": "array", "items": { "type": "string" } }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } }, "additionalProperties": true } ] }, "CompareResponse": { "type": "object", "required": [ "projects", "project_ids", "decision_matrix", "summary", "metadata" ], "properties": { "requested_repos": { "type": "array", "items": { "type": "string" } }, "resolved_repos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "project_ids": { "type": "array", "items": { "type": "string" } }, "order": { "type": "string" }, "context": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" }, "stats": { "type": "object", "additionalProperties": true }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCard" } }, "decision_matrix": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string" }, "recommendation": { "type": "string" }, "tradeoffs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "winner": { "type": "object", "additionalProperties": true }, "reasoning": { "type": "array", "items": { "type": "string" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "NextAction": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" }, "kind": { "type": "string" } }, "additionalProperties": true }, "QualityReportResponse": { "type": "object", "description": "Corpus quality and trust report. release_score is the release gate; data_trust_score and risk_level describe corpus trust.", "required": [ "score", "release_score", "data_trust_score", "risk_level", "risk_summary", "coverage", "metadata" ], "properties": { "score": { "type": "number" }, "release_score": { "type": "number" }, "data_trust_score": { "type": "number" }, "score_summary": { "type": "object", "properties": { "release_score_meaning": { "type": "string" }, "data_trust_score_meaning": { "type": "string" }, "risk_level_meaning": { "type": "string" } }, "additionalProperties": true }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high" ] }, "risk_summary": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "low", "medium", "high" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "low_confidence_classification_rate": { "type": "number" }, "collection_review_rate": { "type": "number" }, "stale_project_rate": { "type": "number" }, "stale_collection_rate": { "type": "number" } }, "additionalProperties": true }, "improvement_plan": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "project_count": { "type": "integer" }, "issue_count": { "type": "integer" }, "error_count": { "type": "integer" }, "warning_count": { "type": "integer" }, "category_distribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "coverage": { "type": "object", "additionalProperties": true }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "QualityReviewResponse": { "type": "object", "description": "Low-confidence classification and collection review queue for data governance.", "required": [ "project_count", "review_count", "items", "metadata" ], "properties": { "project_count": { "type": "integer" }, "review_count": { "type": "integer" }, "low_signal_count": { "type": "integer" }, "medium_signal_count": { "type": "integer" }, "category_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "BenchmarkResponse": { "type": "object", "description": "Public benchmark summary for agents and users evaluating Git.Top recommendation health and trust limits.", "required": [ "name", "evaluation", "explanations", "data_coverage", "review_queue", "known_limitations", "metadata" ], "properties": { "name": { "type": "string" }, "positioning": { "type": "string" }, "summary": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "evaluation": { "type": "object", "properties": { "top1_hit_rate": { "type": "number" }, "top3_hit_rate": { "type": "number" }, "category_accuracy": { "type": "number" }, "deployment_accuracy": { "type": "number" }, "cloudflare_readiness_accuracy": { "type": "number" }, "unacceptable_hit_count": { "type": "integer" }, "review_focus": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "source_report": { "type": "string" } }, "additionalProperties": true }, "explanations": { "type": "object", "properties": { "checks": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "coverage": { "type": "number" }, "source_report": { "type": "string" } }, "additionalProperties": true }, "data_coverage": { "type": "object", "additionalProperties": true }, "review_queue": { "type": "object", "additionalProperties": true }, "known_limitations": { "type": "array", "items": { "type": "string" } }, "recommended_use": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "RoadmapResponse": { "type": "object", "required": [ "positioning", "completion", "phases", "agent_use" ], "properties": { "positioning": { "type": "string" }, "summary": { "type": "string" }, "completion": { "type": "number" }, "current_focus": { "type": "array", "items": { "type": "string" } }, "phases": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_use": { "type": "array", "items": { "type": "string" } }, "pages": { "type": "array", "items": { "type": "string" } }, "api_endpoints": { "type": "array", "items": { "type": "string" } }, "mcp_tools": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "QuickstartResponse": { "type": "object", "required": [ "positioning", "steps", "output_pattern", "trust_policy" ], "properties": { "positioning": { "type": "string" }, "production_endpoints": { "type": "object", "additionalProperties": true }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "output_pattern": { "type": "array", "items": { "type": "string" } }, "trust_policy": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "ClientCompatibilityResponse": { "type": "object", "required": [ "schema_version", "support_policy", "server_contract", "clients" ], "properties": { "name": { "type": "string" }, "schema_version": { "type": "string", "enum": [ "git-top.client-compatibility.v1" ] }, "last_reviewed_at": { "type": "string", "format": "date" }, "core_endpoint": { "type": "string", "format": "uri" }, "full_endpoint": { "type": "string", "format": "uri" }, "support_policy": { "type": "string" }, "server_contract": { "type": "object", "additionalProperties": true }, "clients": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "verification_prompt": { "type": "string" }, "next_required_evidence": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "RecipesResponse": { "type": "object", "required": [ "positioning", "recipes" ], "properties": { "positioning": { "type": "string" }, "recipes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "trust_policy": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "ExamplesResponse": { "type": "object", "required": [ "positioning", "examples", "decision_examples" ], "properties": { "positioning": { "type": "string" }, "examples": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "decision_examples": { "type": "array", "minItems": 10, "items": { "type": "object", "required": [ "id", "title", "user_request", "shortest_rest_path", "shortest_mcp_path", "expected_fields", "example_final_answer", "verification", "next_action" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "user_request": { "type": "string" }, "shortest_rest_path": { "type": "array", "items": { "type": "string" } }, "shortest_mcp_path": { "type": "array", "items": { "type": "string" } }, "expected_fields": { "type": "array", "items": { "type": "string" } }, "example_final_answer": { "type": "string" }, "verification": { "type": "object", "required": [ "scope", "verified_at", "snapshot_id", "source" ], "properties": { "scope": { "type": "string", "enum": [ "local_d1" ] }, "verified_at": { "type": "string", "format": "date" }, "snapshot_id": { "type": "string" }, "source": { "type": "string", "enum": [ "d1" ] } }, "additionalProperties": false }, "external_evidence": { "type": "array", "items": { "type": "object", "required": [ "source", "subject", "verified_at", "url", "facts" ], "properties": { "source": { "type": "string", "enum": [ "github_api" ] }, "subject": { "type": "string" }, "verified_at": { "type": "string", "format": "date" }, "url": { "type": "string", "format": "uri" }, "facts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "next_action": { "type": "string" } }, "additionalProperties": false } }, "trust_policy": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "SyncStatusResponse": { "type": "object", "required": [ "detail", "health", "freshness", "priority" ], "properties": { "detail": { "type": "string", "enum": [ "summary", "full" ] }, "health": { "type": "string" }, "freshness": { "type": "string" }, "cursor": { "type": "object", "additionalProperties": true }, "latest_success": { "type": "object", "additionalProperties": true }, "recent_failures": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "priority": { "type": "object", "required": [ "policy", "counts", "refresh_due_counts", "stale_counts", "stale_rates", "freshness_slo", "capacity" ], "properties": { "policy": { "type": "object", "properties": { "hot_target_days": { "type": "integer" }, "warm_target_days": { "type": "integer" }, "cold_target_days": { "type": "integer" } } }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "refresh_due_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "stale_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "stale_rates": { "type": "object", "additionalProperties": { "type": "number" } }, "freshness_slo": { "$ref": "#/components/schemas/SyncFreshnessSlo" }, "capacity": { "type": "object", "required": [ "scheduled_daily_capacity", "required_daily_syncs", "utilization", "headroom", "target_feasible" ], "properties": { "scheduled_runs_per_day": { "type": "integer" }, "refresh_limit_per_run": { "type": "integer" }, "scheduled_daily_capacity": { "type": "integer" }, "required_daily_syncs": { "type": "integer" }, "utilization": { "type": "number" }, "headroom": { "type": "integer" }, "target_feasible": { "type": "boolean" } } }, "priority_preview": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "refresh_due_preview": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "derived": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "SyncFreshnessSlo": { "type": "object", "required": [ "hot_projects", "whole_corpus" ], "properties": { "hot_projects": { "allOf": [ { "$ref": "#/components/schemas/SyncFreshnessSloSegment" }, { "type": "object", "required": [ "target_hours" ], "properties": { "target_hours": { "type": "integer", "minimum": 1 } } } ] }, "whole_corpus": { "allOf": [ { "$ref": "#/components/schemas/SyncFreshnessSloSegment" }, { "type": "object", "required": [ "target_basis" ], "properties": { "target_basis": { "type": "string", "enum": [ "tier_policy" ] } } } ] } }, "additionalProperties": false }, "SyncFreshnessSloSegment": { "type": "object", "required": [ "total", "within_target", "freshness_rate", "target_rate", "meets_target" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "within_target": { "type": "integer", "minimum": 0 }, "freshness_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "target_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "meets_target": { "type": "boolean" } } }, "GovernanceSummaryResponse": { "type": "object", "properties": { "latest_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tasks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "missing_tasks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "health": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "GovernanceRunsResponse": { "type": "object", "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "WorkflowResponse": { "type": "object", "description": "Guided agent workflow from trust preflight through trends, recommendations, graph, alternatives, score, compare, and final citation.", "required": [ "input", "recommended_sequence", "shortlist", "trend_context", "agent_map", "trust_policy", "metadata" ], "properties": { "positioning": { "type": "string" }, "summary": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "recommended_sequence": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" } }, "shortlist": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } }, "trend_context": { "type": "object", "additionalProperties": true }, "agent_map": { "$ref": "#/components/schemas/AgentMapResponse" }, "trust_policy": { "type": "object", "additionalProperties": true }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "WorkflowStep": { "type": "object", "properties": { "step": { "type": "integer" }, "label": { "type": "string" }, "url": { "type": "string" }, "method": { "type": "string" }, "mcp_tool": { "type": "string" }, "inspect": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "AlternativesResponse": { "type": "object", "required": [ "project", "alternative_matches", "metadata" ], "properties": { "project": { "$ref": "#/components/schemas/ProjectCard" }, "resolved_from": { "type": "object", "additionalProperties": true }, "summary": { "type": "string" }, "stats": { "type": "object", "additionalProperties": true }, "alternatives": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "alternative_matches": { "type": "array", "items": { "$ref": "#/components/schemas/AlternativeMatch" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "comparison_links": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "AlternativeMatch": { "allOf": [ { "$ref": "#/components/schemas/ProjectCard" }, { "type": "object", "properties": { "similarity_score": { "type": "number" }, "alternative_reason": { "type": "string" }, "replacement_type": { "type": "string", "enum": [ "same_use_case", "same_category", "same_deployment", "ecosystem_adjacent" ] }, "fit_summary": { "type": "string" }, "adoption_notes": { "type": "array", "items": { "type": "string" } }, "replacement_risk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "match_signals": { "type": "object", "additionalProperties": true }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } ] }, "RelatedResponse": { "type": "object", "required": [ "related", "metadata" ], "properties": { "project": { "$ref": "#/components/schemas/ProjectCard" }, "resolved_from": { "type": "object", "additionalProperties": true }, "related": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ProjectCard" }, { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } ] } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "GraphResponse": { "type": "object", "required": [ "nodes", "edges", "graph_stats", "metadata" ], "properties": { "focus": { "type": "string" }, "resolved_from": { "type": "object", "additionalProperties": true }, "project": { "$ref": "#/components/schemas/GraphProjectContext" }, "summary": { "type": "string" }, "graph_stats": { "type": "object", "additionalProperties": true }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "relationship_groups": { "type": "object", "additionalProperties": true }, "migration_paths": { "type": "array", "items": { "$ref": "#/components/schemas/MigrationPath" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GraphNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/GraphEdge" } }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "GraphProjectContext": { "type": "object", "properties": { "repo": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "maintainer": { "type": "string" }, "license": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "recent_activity": { "type": "string" } }, "additionalProperties": true }, "GraphNode": { "type": "object", "required": [ "id", "label", "kind" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "project", "category", "deployment", "use_case", "dependency" ] }, "score": { "type": "number" }, "repo": { "type": "string" } }, "additionalProperties": true }, "GraphEdge": { "type": "object", "required": [ "source", "target", "kind", "weight" ], "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "kind": { "type": "string", "enum": [ "alternative", "related", "category", "deployment", "use_case", "dependency" ] }, "reason": { "type": "string" }, "weight": { "type": "number" } }, "additionalProperties": true }, "MigrationPath": { "type": "object", "description": "Heuristic migration decision aid. It is not a drop-in compatibility or production readiness guarantee.", "required": [ "from", "to", "compatibility", "estimated_cost", "shared_signals", "gaps", "validation_steps", "evidence" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "compatibility": { "type": "string", "enum": [ "high", "medium", "low", "unknown" ] }, "estimated_cost": { "type": "string", "enum": [ "low", "medium", "high", "unknown" ] }, "shared_signals": { "type": "array", "items": { "type": "string" } }, "gaps": { "type": "array", "items": { "type": "string" } }, "validation_steps": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "ScoreResponse": { "type": "object", "required": [ "project_id", "score", "git_top_score", "dimensions", "score_confidence", "metadata" ], "properties": { "project": { "$ref": "#/components/schemas/ProjectCard" }, "project_id": { "type": "string" }, "resolved_from": { "type": "object", "additionalProperties": true }, "score": { "type": "number" }, "git_top_score": { "type": "number" }, "quality_score": { "type": "number" }, "agent_score": { "type": "number" }, "verification": { "$ref": "#/components/schemas/VerificationPackage" }, "git_top_score_breakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreDimension" } }, "summary": { "type": "string" }, "adoption_guidance": { "type": "string" }, "risk_flags": { "type": "array", "items": { "type": "string" } }, "score_confidence": { "$ref": "#/components/schemas/ScoreConfidence" }, "strongest_dimension": { "$ref": "#/components/schemas/ScoreDimension" }, "weakest_dimension": { "$ref": "#/components/schemas/ScoreDimension" }, "related_scores": { "type": "object", "additionalProperties": true }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "ScoreDimension": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" }, "weight": { "type": "number" }, "contribution": { "type": "number" }, "explanation": { "type": "string" } }, "additionalProperties": true }, "ScoreConfidence": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "high", "medium", "low" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "evidence_checklist": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "citation_guidance": { "type": "string" } }, "additionalProperties": true }, "AtlasResponse": { "type": "object", "properties": { "ecosystems": { "type": "array", "items": { "$ref": "#/components/schemas/AtlasEcosystem" } }, "ecosystem": { "$ref": "#/components/schemas/AtlasEcosystem" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "AtlasEcosystem": { "type": "object", "required": [ "id", "name", "projects", "stats", "map", "links" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectCard" } }, "stats": { "type": "object", "additionalProperties": true }, "exploration_paths": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } }, "exploration_journeys": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "comparison_paths": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "map": { "$ref": "#/components/schemas/GraphResponse" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "AtlasJourneysResponse": { "type": "object", "required": [ "journeys", "comparison_paths", "stats", "metadata" ], "properties": { "name": { "type": "string" }, "positioning": { "type": "string" }, "journeys": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "comparison_paths": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "additionalProperties": true }, "AgentMapResponse": { "type": "object", "required": [ "surfaces", "short_path", "reference_path", "trust_policy" ], "properties": { "name": { "type": "string" }, "positioning": { "type": "string" }, "purpose": { "type": "string" }, "production_base_url": { "type": "string" }, "rest_base_url": { "type": "string" }, "mcp_endpoint": { "type": "string" }, "openapi_url": { "type": "string" }, "schema_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "short_path": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPathStep" } }, "reference_path": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPathStep" } }, "core_surfaces": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommended_agent_flow": { "type": "array", "items": { "type": "string" } }, "surfaces": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "trust_policy": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "AgentPathStep": { "type": "object", "properties": { "step": { "type": "integer" }, "concept": { "type": "string" }, "rest": { "type": "array", "items": { "type": "string" } }, "mcp_tools": { "type": "array", "items": { "type": "string" } }, "inspect": { "type": "array", "items": { "type": "string" } }, "trust_fields": { "type": "array", "items": { "type": "string" } }, "use_when": { "type": "string" } }, "additionalProperties": true }, "GrpResponse": { "type": "object", "description": "Graph Reasoning Protocol result for planning, composing, comparing, or finding project sets.", "properties": { "solution_paths": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommended_stack": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "explanation": { "type": "array", "items": { "type": "string" } }, "decomposition": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/NormalizedEvidence" }, "caveats": { "type": "array", "items": { "type": "string" } }, "confidence_reason": { "type": "string" }, "source_fields": { "type": "array", "items": { "type": "string" } }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "GrpRequest": { "type": "object", "description": "Graph Reasoning Protocol request for project planning, comparison, discovery, or stack composition.", "required": [ "goal" ], "properties": { "goal": { "type": "string", "description": "Natural-language project selection, comparison, planning, or stack-composition goal." }, "mode": { "type": "string", "enum": [ "plan", "compare", "find", "compose" ], "default": "plan", "description": "Reasoning mode. Defaults to plan when omitted." }, "constraints": { "type": "object", "properties": { "deploy": { "type": "array", "items": { "type": "string" } }, "license": { "type": "string" }, "complexity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "agent_ready": { "type": "boolean" }, "language": { "type": "string" }, "category": { "type": "string" } }, "additionalProperties": true }, "context": { "type": "object", "properties": { "previous_selected_projects": { "type": "array", "items": { "type": "string" } }, "current_stack": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true }, "McpDiscoveryResponse": { "type": "object", "description": "GET /mcp discovery response for agents before JSON-RPC tool calls.", "required": [ "endpoint", "tools" ], "properties": { "endpoint": { "type": "string" }, "docs_url": { "type": "string" }, "schema_url": { "type": "string" }, "health_url": { "type": "string" }, "quality_url": { "type": "string" }, "agent_map_url": { "type": "string" }, "quickstart": { "type": "object", "additionalProperties": true }, "examples": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_map": { "$ref": "#/components/schemas/AgentMapResponse" }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "McpJsonRpcRequest": { "type": "object", "description": "JSON-RPC 2.0 request accepted by POST /mcp.", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ], "description": "Client-chosen request id returned unchanged in success or error responses. Omit for JSON-RPC notifications." }, "method": { "type": "string", "enum": [ "initialize", "notifications/initialized", "tools/list", "tools/call" ], "description": "Supported JSON-RPC method." }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name for tools/call." }, "arguments": { "type": "object", "description": "Tool arguments. Pass require_d1=true for high-confidence D1-backed reads.", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "McpJsonRpcSuccessResponse": { "type": "object", "description": "JSON-RPC 2.0 success response. initialize returns server capabilities, tools/list returns tool metadata, and tools/call returns MCP content blocks; Git.Top serializes structured tool payloads as JSON text in result.content[0].text.", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "result": { "anyOf": [ { "type": "object", "description": "initialize result.", "properties": { "protocolVersion": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "serverInfo": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, { "type": "object", "description": "tools/list result.", "properties": { "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, { "type": "object", "description": "tools/call result. Parse text content as JSON.", "required": [ "content" ], "properties": { "content": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "JSON string containing the structured tool result, usually with metadata.source and metadata.reason. git_top_grp_query includes profile and defaults to a bounded compact graph response; use profile=full for the complete graph." } }, "additionalProperties": true } } }, "additionalProperties": true } ] } }, "additionalProperties": true }, "McpJsonRpcErrorResponse": { "type": "object", "description": "JSON-RPC 2.0 error response. Strict D1 failures use code -32003; unresolved singular project lookups use code -32005, while stale pagination cursors use -32004.", "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "JSON-RPC error code. Common values include -32700 parse error, -32601 method/tool not found, -32602 invalid params, -32003 D1 required, -32004 stale pagination cursor, and -32005 project not found." }, "message": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "ClassificationOverrideInput": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string", "description": "GitHub owner/repo identifier." }, "category": { "type": "string", "enum": [ "agent_framework", "coding_agent", "browser_agent", "rag_framework", "vector_database", "llm_gateway", "llm_eval", "prompt_tooling", "workflow_automation", "local_llm_runtime", "ai_app_template", "mcp_server", "ai_observability", "other" ] }, "difficulty": { "type": "string", "enum": [ "beginner", "intermediate", "advanced" ] }, "deployment": { "type": "array", "items": { "type": "string" } }, "cloudflare_ready": { "type": "boolean" }, "classification": { "type": "object", "description": "Optional classification evidence override." }, "notes": { "type": "string" }, "reviewed_by": { "type": "string" }, "reviewed_at": { "type": "string", "format": "date-time" } } }, "RecommendationRequest": { "type": "object", "properties": { "use_case": { "type": "string" }, "useCase": { "type": "string" }, "deployment": { "type": "string" }, "category": { "type": "string" }, "license": { "type": "string" }, "difficulty": { "type": "string" }, "language": { "type": "string" }, "cloudflare_ready": { "type": "boolean" }, "limit": { "type": "integer" }, "constraints": { "type": "object", "properties": { "deployment": { "type": "string" }, "category": { "type": "string" }, "license": { "type": "string" }, "difficulty": { "type": "string" }, "language": { "type": "string" }, "cloudflare_ready": { "type": "boolean" } } } } }, "WorkflowRequest": { "type": "object", "properties": { "intent": { "type": "string" }, "goal": { "type": "string" }, "use_case": { "type": "string" }, "useCase": { "type": "string" }, "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" }, "deployment": { "type": "string" }, "category": { "type": "string" }, "license": { "type": "string" }, "difficulty": { "type": "string" }, "language": { "type": "string" }, "cloudflare_ready": { "type": "boolean" }, "limit": { "type": "integer" }, "constraints": { "type": "object", "properties": { "deployment": { "type": "string" }, "category": { "type": "string" }, "license": { "type": "string" }, "difficulty": { "type": "string" }, "language": { "type": "string" }, "cloudflare_ready": { "type": "boolean" } } } } }, "CompareRequest": { "type": "object", "properties": { "project_ids": { "type": "array", "items": { "type": "string" } }, "projects": { "type": "array", "items": { "type": "string" } }, "repos": { "oneOf": [ { "type": "string", "description": "Comma-separated owner/repo list." }, { "type": "array", "items": { "type": "string" } } ] }, "deployment": { "type": "string" } } }, "AlternativesRequest": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" }, "limit": { "type": "integer" } } }, "ProjectLookupRequest": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" }, "related_limit": { "type": "integer" } } }, "ProjectSummary": { "type": "object", "required": [ "tl_dr", "purpose", "inputs", "outputs", "good_for", "not_good_for", "deployment", "alternatives" ], "properties": { "tl_dr": { "type": "string", "description": "One-sentence project overview for agents." }, "purpose": { "type": "string", "description": "Longer agent-facing project purpose." }, "install": { "type": [ "string", "null" ], "description": "Conservative install or setup hint when Git.Top can infer one." }, "inputs": { "type": "array", "items": { "type": "string" } }, "outputs": { "type": "array", "items": { "type": "string" } }, "good_for": { "type": "array", "items": { "type": "string" } }, "not_good_for": { "type": "array", "items": { "type": "string" } }, "deployment": { "type": "array", "items": { "type": "string" } }, "alternatives": { "type": "array", "items": { "type": "object", "required": [ "repo", "reason" ], "properties": { "repo": { "type": "string" }, "reason": { "type": "string" } } } } } }, "RelatedRequest": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" }, "limit": { "type": "integer" } } }, "ScoreRequest": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" } } }, "GraphRequest": { "type": "object", "properties": { "project_id": { "type": "string" }, "projectId": { "type": "string" }, "repo": { "type": "string" }, "focus": { "type": "string" }, "limit": { "type": "integer" } } }, "GovernanceRunInput": { "type": "object", "required": [ "task", "status" ], "properties": { "id": { "type": "string" }, "task": { "type": "string", "description": "Short governance task identifier." }, "status": { "type": "string", "enum": [ "success", "failed", "running", "skipped" ] }, "trigger": { "type": "string", "enum": [ "github_actions", "cron", "admin", "manual" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer" }, "summary": { "type": "object" }, "report_url": { "type": "string" }, "error": { "type": "string" } } } } } }