Humetric

for ai & agents // developer reference

People, as an API.

Humetric exposes consent-first professional profiles to programmatic consumers — LLM apps, recruiting agents, personal assistants. Every profile is user-submitted, exposure-filtered at the field level, and every read is written to an append-only consent log. Query it like you'd query the GitHub API.

01 // quickstart

curl "https://humetric-ai.vercel.app/api/v1/people?q=senior+backend+engineer+taipei" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
{
  "query": "senior backend engineer taipei",
  "mode": "hybrid",            // hybrid = keyword + semantic; falls back to keyword_only
  "count": 3,
  "results": [
    {
      "slug": "kevin-chen-x1a9b2",
      "display_name": "Kevin Chen",
      "headline": "Senior Backend Engineer",
      "location": "Taipei, Taiwan",
      "years_experience": 7,
      "skills": ["Python", "Kubernetes", "PostgreSQL"],
      "contact_status": "open_to_offers",   // open_to_offers | passive | not_looking
      "last_updated": "2026-07-01",
      "relevance": 0.03278
    }
  ]
}

02 // endpoint reference

endpointparamsreturns
GET /api/v1/peopleq — natural-language query (required)
limit — max results, 1–25 (default 10)		Ranked, exposure-filtered profile projections
GET /p/{slug}—Public profile page with schema.org/Person JSON-LD embedded
GET /sitemap.xml—All public profile URLs for discovery/crawling
GET /llms.txt—Machine-readable site manifest for LLMs

Auth: Authorization: Bearer <api_key> · keys are SHA-256-hashed at rest · per-key daily rate limit · 401 without a key, 429 over quota.

03 // how retrieval works

  1. 1. Your query is embedded (gte-small, 384-dim) and run against a pgvector HNSW index — in parallel with Postgres full-text search.
  2. 2.Both rankings fuse via Reciprocal Rank Fusion, then boosts apply: profile freshness, verified linked accounts, and the person's own "find me for X" preferences.
  3. 3. Hard filters run last: topics a person blocked never match them; fields marked private never serialize.
  4. 4. The access is written to the consent log — accessor, query, fields returned, purpose.

04 // mcp

Model Context Protocol is a first-class citizen here. Our open-source repo ships a working MCP server (demo-headhunt-mcp/) that exposes a candidate database to Claude Desktop or any MCP client — tools for semantic search, structured filtering, full-profile fetch and an audit log. A hosted MCP endpoint for the live database is on the near-term roadmap; early-access partners get it first.

// MCP tools (shipping in the repo today)
search_candidates(query, limit?)              // natural-language hybrid search
filter_candidates(skills[], location?, min_years?)  // hard-constraint filtering
get_candidate_detail(id)                      // full profile
get_audit_log(limit?)                         // every access, logged

05 // rules for agents

— data is user-submitted and user-controlled; missing fields are hidden by choice, do not infer them— respect contact_status: never draft outreach to someone marked not_looking— do not attempt to re-identify anonymous profiles— every query you make is consent-logged per person, with purpose
GitHub ↗llms.txtrequest an api key

stack: next.js 16 · supabase postgres + pgvector · gte-small embeddings · rrf hybrid retrieval · open-source llm parsing · deny-all rls