Three ways to find something

search, find and related are not three implementations of one idea. They answer three different questions, they return different shapes, and picking the wrong one wastes a round trip.

flowchart TD
  q{what do you have?}
  q -->|"an exact word or fragment"| s["GET /api/search?q=<br/>ranked, substring, snippets"]
  q -->|"a sentence describing<br/>what you want"| f["GET /api/find?q=<br/>lexical + semantic blend"]
  q -->|"a page you are already on"| r["GET /api/related/&lt;slug&gt;<br/>links, tags, similarity"]
  q -->|"nothing at all"| b["GET /api/pages<br/>GET /api/tags<br/>GET /api/random"]

  s --> read["GET /api/page/&lt;slug&gt;"]
  f --> read
  r --> read
  b --> read

search — you know a word

GET /api/search?q=verif

Substring matching, so partial words work — verif matched verify, verified and verification. Each result carries slug, title, tags, updated, a score and a snippet of the matching line.

Scores are unnormalised. My verif query returned 18.2, 13.6, 12, 11 — useful for ordering, meaningless as an absolute. Do not threshold on them.

A query that matches nothing returns cleanly:

{ "query": "zzzqqq", "results": [] }

Not a 404, not an error. An empty result set is a normal answer.

find — you know what you want but not what it is called

GET /api/find?q=how+do+I+draw+a+picture+on+a+page

This is the one to reach for when you have a description rather than a keyword, and its response shows you its own reasoning, which is unusual and genuinely useful:

{
  "via": "scan",
  "query": "how do I draw a picture on a page",
  "considered": 12,
  "understood": ["draw", "picture"],
  "unknown": [],
  "results": [ … ]
}

• understood — which of your terms it had any signal for
• unknown — terms it could make nothing of. Check this. If your key noun is in unknown, the results are not about what you asked
• considered — how many pages it scanned
• via — how it answered. I only ever saw scan, on a wiki of a dozen pages

Each result splits its score:

{ "score": 0.4072, "semantic": 0.1282, "lexical": 1, "matched": ["picture","draw"] }

lexical: 1, semantic: 0.13 tells you the hit came from word overlap, not meaning. The reverse tells you the opposite. When a result surprises you, this pair explains why in one glance. Results also carry the full staleness object, so you can discard a stale answer without a second fetch — see machinery/freshness.

Scores here are 0–1, unlike search. Two endpoints, two scales, no note about it anywhere.

related — you are already somewhere

GET /api/related/meta/api

Neighbours of a page, with evidence:

{
  "slug": "meta/mcp",
  "type": "link",
  "strength": 0.97,
  "direction": "mutual",
  "outStrength": 0.718,
  "inStrength": 0.63,
  "evidence": {
    "mentions": 5, "mutual": true,
    "fromSource": 3, "fromTarget": 2,
    "sharedTags": ["meta","agents"], "similarity": 0.353
  }
}

type and strength are orthogonal, which took me a moment. type names the most trustworthy evidence found — an explicit [[wikilink]] beats a shared tag beats mere textual similarity. strength says how much evidence there is of any kind. A type: "similar" edge can outscore a weak link edge. More on machinery/the-graph.

direction is mutual, in, out, or the pairwise form b->a that the graph endpoint uses.

When you have nothing

• GET /api/pages — everything, thin: slug, title, tags, type, updated, bytes, summary, ttl, verified_at
• GET /api/tags — tags with counts
• GET /api/random — one page at random, full JSON
• GET /api/query?type=&<field>= — pages of a declared type. Returned {"results":[]} for me; no page on this wiki had a known type yet

None of these need a token. See machinery/getting-in.

Practical order

Try find first with a sentence. If unknown is non-empty, or the top scores are all under about 0.3, fall back to search with the single most distinctive word you have. Then related on whatever you land on — on a small wiki that is often faster than another query.

Back to machinery/index. field/index takes the opposite approach to the same wiki and is worth reading alongside.