Evidence Query

Provenance-grounded natural-language Q&A (§197)

POST a natural-language question about a supported U.S. healthcare-provider supply dataset. Returns a short answer plus the evidence fields available to the selected resolver, which can include source URL, observation timestamp, methodology, confidence, and limitations. Fields can be null when the audit-pack registry does not supply them.

Pipeline (SQL-injection-safe by construction):

  1. Pre-flight filters reject prompt-injection signatures, payment/claims questions, predictions, vendor comparisons, and single-provider PII fishing before any LLM call.
  2. Anthropic Sonnet maps the question to a strict whitelist intent (dataset slug + state code + intent kind) via tool-use; the input schema constrains output to the registered enums. Output is then runtime-validated.
  3. A typed resolver dispatches to hand-written, pre-existing data accessors. The classifier output never produces SQL — there is no query() call that concatenates LLM output into a query string anywhere in the pipeline.
  4. Available claim evidence is attached from the audit-pack registry; a second LLM call writes the summary constrained to the resolver's exact numbers, with a deterministic-template fallback.

County-scope honesty: NPPES has no public county-of-practice field. Queries scoped to a county return state-level supply with geo_widened: true flagged in the answer and an explicit limitation in the evidence trail.

Refusal codes: out_of_scope, predictions, payment_data, competitor_compare, individual_provider_lookup, prompt_injection, classification_failed. Refusals return HTTP 200 with status: "refusal" and a machine-readable refusal.code.

Demo (no auth, 10 queries / 24h per IP): POST /api/evidence-query/demo with the same body shape.

post/api/v1/evidence-query

Request

  • Base URL: https://fonteum.com
  • URL: https://fonteum.com/api/v1/evidence-query
  • Auth: HTTP bearer

Request body

querystring required

Example request

{
  "query": "How many active dermatologists practice in Texas, and how is that number sourced?"
}

Response

Answer + evidence trail (or refusal).

Example response

{
  "data": {
    "answer": {
      "methodology_version": "v2026.05.0"
    }
  },
  "meta": {
    "request_id": "req_abc123def456",
    "freshness": [
      {
        "source_id": "oig-leie"
      }
    ],
    "freshness_policy": {
      "max_staleness": "48h",
      "max_staleness_hours": 48
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.