Search API.

Request

JSON body with two fields:

• q (string, required, 1–4000 chars) — the natural-language query.
• limit (number, optional, default 25, max 100) — maximum number of results to return.

POST /api/v1/search HTTP/1.1
Host: fonteum.com
Authorization: Bearer fnt_DEMO_PUBLIC_V1
Content-Type: application/json

{
  "q": "dermatologists in Texas with high patient density",
  "limit": 25
}

Response

Server-Sent Events (Content-Type: text/event-stream). Each frame is one JSON object on a single data: line followed by a blank line. Five event types:

1. meta — sent first; carries the parsed filters + a rewriterUsed boolean signalling whether the LLM rewriter ran successfully.
2. result — one per ranked hit; carries the provider record + similarity score + the provenance fields available for that hit.
3. error — sent if rewrite, embed, or search fails. Carries stage + retryable + message.
4. complete — always sent last; carries total + took_ms.

data: {"type":"meta","filters":{"vertical":"dermatologists","state":"TX"},"rewriterUsed":true,"rate_remaining":{"minute":59,"day":999}}

data: {"type":"result","rank":1,"npi":"1234567893","vertical":"dermatologists","vertical_display":"Dermatology","taxonomy_primary":"207N00000X","state":"TX","city":"AUSTIN","similarity":0.84,"cosine_distance":0.16,"snapshot_date":"2026-05-06","provenance":{"_source":"CMS NPPES NPI Registry (public API)","_source_url":"https://npiregistry.cms.hhs.gov/api/","_dataset_id":"nppes-npi-registry","_snapshot":"2026-05-06","_methodology":"v2026.05.0","_last_checked":"2026-05-09T07:00:00.000Z","_confidence":1.0,"_data_availability":["present"]}}

data: {"type":"complete","total":25,"took_ms":284}

Source and capture context

A result event can carry a provenance object using the following fourteen-field schema. Individual fields may be null or absent:

• _source — human-readable name of the upstream source.
• _source_url — canonical URL of the upstream source.
• _dataset_id — stable identifier (e.g. nppes-npi-registry).
• _snapshot — release date of the snapshot the result came from.
• _methodology — methodology version (e.g. v2026.05.0; pin a citation by methodology version).
• _last_checked — ISO timestamp of the response build.
• _confidence — 0.00–1.00; confidence in the hydration-from-snapshot path (1.0 for direct NPPES matches).
• _data_availability — array; e.g. ["present"] or ["pending_refresh"].
• _pipeline_version — git commit SHA of the ingestion code (nullable).
• _doi — DOI for the methodology version (nullable, not yet issued).
• _license — SPDX identifier, e.g. US-Government-Works (nullable).
• _coverage_period_start — ISO date data coverage begins (nullable).
• _coverage_period_end — ISO date data coverage ends or "ongoing" (nullable).
• _slsa_provenance_url — URL to the SLSA Build Level 3 artifact (nullable).

Rate limits

Account keys use their configured minute and day windows. The read-only sample key uses these per-trusted-source-IP windows:

• 20 requests / minute.
• 100 requests / day.

Both buckets must allow the request. Exceeding either returns 429 with a Retry-After header and details.retry_after_sec field. When both windows are full, the later reset is returned. Authenticated responses also carry X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Day headers for client-side back-off awareness.

curl

curl -N -X POST https://fonteum.com/api/v1/search \
  -H "Authorization: Bearer fnt_DEMO_PUBLIC_V1" -H "Content-Type: application/json" \
  -d '{"q":"dermatologists in Texas","limit":25}'

The -Nflag disables curl’s buffering so SSE frames arrive as they’re produced.

Node (fetch)

const res = await fetch("https://fonteum.com/api/v1/search", {
  method: "POST",
  headers: { "Authorization": "Bearer fnt_DEMO_PUBLIC_V1", "Content-Type": "application/json" },
  body: JSON.stringify({ q: "dermatologists in Texas", limit: 25 }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let idx;
  while ((idx = buf.indexOf("\n\n")) !== -1) {
    const frame = buf.slice(0, idx).trim();
    buf = buf.slice(idx + 2);
    const ev = JSON.parse(frame.replace(/^data:\s*/, ""));
    console.log(ev);
  }
}

Python (httpx)

import httpx, json

with httpx.stream("POST", "https://fonteum.com/api/v1/search",
    json={"q": "dermatologists in Texas", "limit": 25},
    headers={"Authorization": "Bearer fnt_DEMO_PUBLIC_V1", "Content-Type": "application/json"}, timeout=30) as r:
    buf = ""
    for chunk in r.iter_text():
        buf += chunk
        while "\n\n" in buf:
            frame, buf = buf.split("\n\n", 1)
            payload = frame.lstrip("data: ").strip()
            if payload:
                ev = json.loads(payload)
                print(ev)

Errors

• 400 invalid_json — body is not parseable JSON.
• 400 missing_q — q field missing or empty.
• 400 query_too_long — q exceeds 4000 chars.
• 429 rate_limit_exceeded— the API key’s minute or day quota is exhausted. The public sample is additionally sharded by trusted source IP. Includes details.retry_after_sec.
• error event mid-stream — rewrite, embed, or search failed. The endpoint always sends a final complete event so consumers have a deterministic close signal.