ghfind API documentation

ghfind scores any GitHub account 0-100 for real contribution value and trustworthiness with a deterministic, open-source engine. Everything on the site is also available programmatically: a public REST API, an MCP server for AI agents, and official SDKs. This page documents all of them.

ghfind REST API

Base URL: https://ghfind.com. Scoring reads need no authentication. Errors are structured JSON ({error, message, hint}), responses carry RateLimit-* headers, and list endpoints support limit/offset pagination.

GET /api/score/{username}: Deterministic 0-100 score, tier, and six-dimension breakdown. Scores unseen accounts live; no auth, no LLM.
POST /api/scan: Full deterministic scan payload: raw metrics, top repositories, recent pull requests, red flags, sub-scores.
POST /api/roast: AI-written roast report (the only LLM endpoint; supports bring-your-own key).
POST /api/vs-verdict: Head-to-head verdict for two accounts.
GET /api/leaderboard: Ranked developers by trending, score, heat, or progress; paginated via limit/offset.
GET /api/developers: Developer directory by language, organization, or contributed repository; paginated.
GET /api/search-users: Prefix search across already-scored accounts.
GET /api/stats: Platform totals (number of scored accounts).
GET /api/badge/{username}: SVG score badge to embed in a README.

ghfind MCP server

A Streamable HTTP Model Context Protocol server lives at https://ghfind.com/mcp (no auth, per-IP rate limited, read-only). Add it to Claude, Cursor, or any MCP client to score and compare GitHub accounts from inside the agent.

score_user — 0-100 score, tier, and six-dimension breakdown for any GitHub login.
scan_user — Full scan payload: metrics, top repos, recent PRs, red flags.
compare_users — Deterministic head-to-head comparison with winner and score gap.
get_leaderboard — Ranked public developers for discovery.
search_users — Prefix search over scored accounts.

Authentication

Read endpoints are public. Write endpoints (POST /api/scan, POST /api/roast) accept a browser Turnstile verification or a Bearer API key. Agents should read the machine walkthrough at /auth.md.

Official SDKs & CLI

@hikariming/ghfind (npm) — JavaScript / TypeScript SDK and CLI: npm install -g @hikariming/ghfind
ghfind (PyPI) — Python SDK: pip install --upgrade ghfind
ghfind CLI — ghfind score {username} -o json · ghfind scan · ghfind roast · ghfind leaderboard · ghfind stats

Machine-readable surfaces

/openapi.json — OpenAPI 3.1 spec of every public endpoint
/llms.txt — Agent-facing guide with markdown links to every surface
/index.md — Markdown twin of the homepage (also served on Accept: text/markdown)
/.well-known/agent-card.json — A2A agent card, MCP server card, API catalog and skills under /.well-known/