Search in plain English

POST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events.

Describe who you are looking for in a sentence and get back a ranked shortlist of real people, with the evidence behind every pick. This is the search the product is built around, unchanged and unabridged.

POST/api/v1/search~10 reserved, reconciled down

One sentence in, a ranked shortlist out. Blocking by default, or streamed as server-sent events.

The request

Body

querystringoptional: One sentence describing who you want. Include the constraints that matter: role, seniority, location, what they have built. Naming a count is honoured. Use this or messages.
messagesarrayoptional: A conversation of { role, content } objects, for follow-ups. Roles are user and assistant. Use this or query.
streambooleanoptional: Return server-sent events instead of one JSON body. Defaults to false.
rerankbooleanoptional: Rank and trim to a shortlist. Defaults to true. Set false to get every unique person the sources returned, unranked.

curl https://www.refolk.ai/api/v1/search \
  -H "Authorization: Bearer $REFOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Series A fintech CTOs in London who came from a bank"}'

Run this in the playgroundSigned in, on your own account and credits.

Follow-ups

Pass the conversation back and the second question is read in the light of the first, exactly as it is in the app.

{
  "messages": [
    { "role": "user", "content": "Founders of seed-stage fintechs in London" },
    { "role": "assistant", "content": "Found 25." },
    { "role": "user", "content": "Only the ones who were engineers first" }
  ]
}

Fifty messages and a hundred thousand characters are the ceiling. Past either, start a new conversation: the whole history is read on every turn, so a long one is paid for again each time.

The response

Fields

answerstringrequired: A short written summary of the run.
peoplearrayrequired: The shortlist. Each carries a name, a stable key, whatever role and location resolved, a reason for the match, and signals, which is the evidence behind it.
companiesarrayrequired: Populated when the question was about companies instead. A query about fintechs in Berlin returns these.
reposarrayrequired: Populated when the question was about repositories.
creditsobjectrequired: charged and balance for this run.

Profile photos come back as absolute URLs on this site rather than wherever the image is hosted, so they can be rendered anywhere without leaking where they came from.

Streaming

A search takes tens of seconds. If something with a screen is waiting on it, stream it: one JSON object per data: line, in the order things happened.

const res = await fetch("https://www.refolk.ai/api/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REFOLK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "Rust maintainers in Europe", stream: true }),
});

const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const lines = buffer.split("\n\n");
  buffer = lines.pop() ?? "";
  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const event = JSON.parse(line.slice(6));
    if (event.type === "people") console.log(event.people.length, "found");
  }
}

The event types, in the order you will meet them:

Type	Meaning
`step`	A stage of the search started.
`step_done`	It finished, with `durationMs`, and `error` if it failed.
`token`	A fragment of the written answer.
`people_partial`	What one source found, before the merge. Superseded by `people`.
`people`, `companies`, `repos`	The results.
`balance`	What the run cost, once it has settled.
`done`	The run finished.
`error`	The run failed, with a message.

How long to wait

Thirty to ninety seconds is normal, and a hard search can take longer. Set the client timeout at three minutes or more. Two searches per key may run at once; a third is refused with a 429 rather than queued.

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.

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.

The request#

Follow-ups#

The response#

Streaming#