API and MCP server
People search your
agents can call.
Describe who you are looking for in a sentence and get real people back, ranked, with the evidence behind every pick. Or send an exact filter set and get the same page every time. One key, one credit balance, and an MCP server so an assistant can do it without you writing any code at all.
500 free credits on signup, topping back up to 250 a month on the free tier. No separate API plan: a key spends the same balance the app does.
{
"query": "|",
"stream": true
}people[] · 0
- Waiting on the first pick.
A replay of one streamed request, at the speed it happens. The people are invented; the fields are the ones the endpoint returns.
Three ways in
Two searches, and one of them needs no code.
- Search in plain EnglishPOST a sentence. I plan the search, read public sources live, cross-reference them, and hand back a ranked shortlist with a reason and the signals behind every name. Blocking, or streamed as server-sent events so your own UI can show the work.POST /v1/search
- Search with filtersPOST an exact filter set: titles, skills, seniority, employer size, location, years in. No model runs and nothing is ranked, so the same filters return the same page tomorrow. 10 credit a call, cursor-paginated.POST /v1/people/search
- Or no code at allPoint Claude, Cursor, VS Code, or anything else that speaks the Model Context Protocol at one URL, and the assistant gets 4 tools it can reach for mid-conversation. One header, no session to establish./api/mcp
The whole thing
One endpoint. One header. One sentence.
There is nothing to install. It is JSON over HTTPS with a bearer key, which means the integration is a fetch call and the debugging is a curl command. Add "stream": true and the same request comes back as server-sent events, one JSON object per line, in the order things happened.
- A key, never a cookie. Bearer keys, hashed at rest, shown once, revoked one at a time. No OAuth dance and no session to manage.
- Paid for what ran. One price a search, taken before it runs. A run that errors having found nobody is refunded in full.
- Read live, not exported. Public LinkedIn and Crunchbase records, GitHub, and the sources they link to, read at search time rather than from a stale dump.
- Docs a model can read. Every page is served as plain Markdown, and there is an OpenAPI document if you would rather generate a client than write one.
curl https://www.refolk.ai/api/v1/search \
-H "Authorization: Bearer $REFOLK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Staff backend engineers in NYC who shipped Rust in production"}'Full request and response shapes in the reference, or run it against your own account in the playground.
What people build
Sourcing, on your side of the wire.
- A headhunting agent in your own productHand it the brief your user typed and stream the run back to them. Every name arrives with a reason attached, so your interface has something to show rather than a spinner and a list.
- A watchlist that runs overnightWrite the brief once in English, keep the filter set it produces, and re-run it on a schedule for 10 credit a page. Nothing is ranked, so today's page is comparable to yesterday's.
- Shortlists inside a chatAsk your assistant for the maintainers of a library, or for staff engineers in Berlin, and get people back in the thread. It calls the same searches the app does, on your key.
- Your own ranking on top of mineSend rerank: false and every unique person the sources returned comes back unranked with the evidence attached, for you to score however your product scores people.
MCP server
Give your assistant 4 tools.
One URL and one header, over Streamable HTTP. No session to establish and no local process to keep alive: each message is answered in the response that carried it, which is what makes it safe to point a whole team at.
{
"mcpServers": {
"refolk": {
"url": "https://www.refolk.ai/api/mcp",
"headers": { "Authorization": "Bearer rfk_live_your_key_here" }
}
}
}Setup, client by client: Claude Code, Cursor, Claude Desktop, VS Code, Windsurf, Cline.
- refolk_search_people100 credits
Search for people in plain English
- refolk_filter_people10 credits
Search for people with exact filters
- refolk_plan_filters1 credit
Turn a description into a filter set
- refolk_credit_balancefree
Check the credit balance
Each tool states what it costs in its own description, because an assistant spending somebody's credits should be able to say so first.
Endpoints and cost
Five endpoints. Two of them free.
- POST/v1/searchA sentence in, a ranked shortlist with evidence out100 credits
- POST/v1/people/searchA filter set in, a deterministic page out10 credit
- POST/v1/people/translateA sentence into the filter set, without searching1 credit
- GET/v1/creditsBalance, monthly floor, and what each call costsfree
- GET/v1/meWhich key you are holdingfree
Rate limits are per key rather than per account, so one runaway script cannot take your other integrations down with it. Credits and limits has the numbers, the refund rules, and what a 429 carries.
Documentation
Every page, and a Markdown copy of it.
Getting started
- QuickstartCreate a key, run your first search, and read what comes back. A working request in under two minutes, in curl, TypeScript, and Python.
- AuthenticationHow API keys work: creating one, sending it, rotating it, and what happens when one leaks. Keys are shown once and hashed at rest.
- Credits and limitsWhat each call costs, what a failed run is charged, what the rate limits are, and how to check a balance before a long run.
- PlaygroundRun any endpoint from the browser, signed in, on your own credits. Prefilled examples, the real response, and the equivalent curl for your own code.
Reference
- Search in plain EnglishPOST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events.
- Search with filtersPOST /v1/people/search. An exact filter set in, a deterministic page of people out, one flat price a page. Every field, every allowed value, and how to paginate.
- ErrorsOne error shape for every endpoint, a closed set of types, and which of them are worth retrying. What gets refunded when a call fails.
Integrations
Every page here is also served as plain Markdown: add .md to any URL, or start from /developers/index.md. There is an OpenAPI document if you would rather generate a client than write one, and /llms.txt indexes the whole site for an assistant reading on your behalf.
Questions developers ask
What does the API do?
It finds real people. One endpoint takes a sentence and returns a ranked shortlist with the evidence behind every pick; another takes an exact filter set and returns a deterministic, paginated page. Both are the same searches the Refolk interface runs, on the same account and the same credit balance.
How do I authenticate?
With an API key, sent as an Authorization header, or as X-Api-Key. Keys are created on the API page in your account, shown once, hashed at rest, and revocable one at a time. Session cookies are deliberately not accepted, because a cookie is authority a browser attaches on its own.
What does it cost?
Credits, by the call. A filtered search is 10 credits whatever the page size, turning a sentence into a filter set is 1 credit, and a plain-English search is 100 credits flat, or nothing at all when it finds nobody. Reading the balance is free. A new account starts with 500 credits and the free tier tops back up to 250 each month. There is no separate API plan and no per-seat pricing.
Is there an MCP server?
Yes, at https://www.refolk.ai/api/mcp, over Streamable HTTP, with 4 tools: search in plain English, search with filters, turn a sentence into a filter set, and check the balance. There are setup pages for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and Cline, each with the exact config to paste.
How long does a search take?
A plain-English search takes thirty to ninety seconds, because it is reading sources live rather than querying a table. Stream it as server-sent events, set your client timeout to three minutes or more, and do not put it on a request path somebody is waiting on. A filtered search returns in a second or two.
Are the results repeatable?
The filtered search is: no model runs and nothing is ranked, so the same filter set returns the same page tomorrow. The plain-English search is not, by design, because it reads live sources and ranks what it finds. Build a pipeline on the first and use the second where judgement is needed.
Is there an SDK?
No SDK to install and none needed. It is JSON over HTTPS with one header, so fetch, requests, or curl is enough. There is an OpenAPI document at /api/v1/openapi.json if you would rather generate a client, and every documentation page is served as plain Markdown for the assistant writing the code.
What happens when a call fails?
Every endpoint returns the same error shape with a closed set of types, so a client can branch on the error type rather than parse prose. Rate limits carry a Retry-After header. A filtered search or a translation that fails upstream is refunded in full, and so is a plain-English search that errors having produced nothing.
Where does the data come from?
Public sources, read at search time: public LinkedIn and Crunchbase records, GitHub, company sites, and the pages they link to. Every person in a plain-English result carries the signals behind the pick, so you can check the reasoning rather than trust a score.
Try it on the search you came here for
Stop building boolean strings. Just describe the person.
Type one sentence. I plan the search, read GitHub, public LinkedIn and Crunchbase records, and the open web as it is right now, and hand back a ranked list with the reason next to every name.
01Describe them
One plain sentence. Role, city, stack, stage, whatever matters to you.
02I read the web live
GitHub, public LinkedIn and Crunchbase records, the open web. Not a database that went stale last quarter.
03You read the shortlist
Ranked, with the reasoning under every name. Open a profile, ask a follow-up, narrow it down.
- Staff backend engineers in NYC who shipped Rust in production
- Series A fintechs in SF under 50 people, growing headcount this year
- Maintainers of fast-growing Rust web frameworks on GitHub
- No boolean, no filters, no seat to buy. One box.
- Read at search time, so a profile updated yesterday counts today.
- Every step visible as it runs, every name with its reason.
500 free credits on sign-up. No card, no demo call. See real searches.