---
title: "Provenance-grounded natural-language Q&A (§197)"
method: POST
path: "/api/v1/evidence-query"
tags: ["Evidence Query"]
---

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

`POST /api/v1/evidence-query`

## Request

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

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.

## Request body

- object
  - `query` string, required
  - `options` object
    - `max_evidence_items` integer

## Response `200`

Answer + evidence trail (or refusal).

- object
  - `data` object
    - `status` 'ok' | 'refusal'
    - `answer` object, nullable
      - `summary` string
      - `value` number, nullable
      - `unit` string, nullable
      - `dataset` string
      - `dataset_slug` string
      - `methodology_version` string
      - `geo_widened` boolean
    - `evidence` object[]
      - `claim` string
      - `source` object
        - `name` string
        - `tier` union
          - integer
          - string
        - `url` string, uri, nullable
        - `last_checked` string, date-time
        - `artifact_snapshot_at` string, date-time: Aggregate/static artifact snapshot represented by the claim; not a publisher release or Fonteum content-change timestamp.
        - `timestamp_basis` 'artifact_snapshot'
        - `confidence` number
      - `methodology` object
        - `url` string, uri
        - `version` string
        - `limitations` string[]
    - `refusal` object, nullable
      - `code` string
      - `message` string
  - `meta` ResponseMeta
    - `request_id` string, required
    - `api_version` 'v1', required
    - `data_freshness` union, required: One source block or an array of source blocks. Fields keep content-change, publisher-release, artifact-snapshot, coverage, check, and observation timestamps separate; only a proved canonical content transition can make last_refreshed non-null.
      - DataFreshness
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
      - DataFreshness[]
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
    - `methodology_url` string, uri, required
    - `limitations_url` string, uri, required
    - `documentation_url` string, uri
    - `geo_scope_note` string
    - `pagination` object
      - `total` integer
      - `page` integer
      - `per_page` integer
    - `freshness` FreshnessBlock[]: Typed per-source stored-observation timing: snapshot date, configured target, and a computed age state. This measures the stored observation against Fonteum's configured target, not upstream publisher freshness. A `current` state requires a dated stored snapshot; an unconfirmable date renders `unknown`.
      - `source_id` string, required
      - `snapshot` string, date, nullable, required: Source publication date; null when unavailable (state then `unknown`).
      - `last_checked` string, date-time, required: Serve-time — the only `now` field.
      - `sla_days` integer, nullable
      - `sla_hours` integer, nullable
      - `age_hours` integer, nullable
      - `age_days` integer, nullable
      - `within_sla` boolean, nullable
      - `state` 'current' | 'degraded' | 'stale' | 'unknown', required
    - `freshness_policy` FreshnessPolicy: Present only when the request set `max_staleness`. Reports whether each consulted stored source observation met the caller's age bar; it does not assert that the upstream publisher released newer data.
      - `requested` true, required
      - `max_staleness` string, required
      - `max_staleness_hours` number, required
      - `mode` 'flag' | 'reject', required
      - `stale` boolean, required
      - `stale_sources` object[], required
        - `source_id` string
        - `state` 'current' | 'degraded' | 'stale' | 'unknown'
        - `age_hours` integer, nullable
        - `reason` 'exceeds_max_staleness' | 'freshness_unknown'
    - `attestation` TrustMark, required: Re-checkable attribution attached to v1 response metadata. The chain-head value is a 32-byte content hash, not an Ed25519 signature. Per-snapshot witness signatures use a separately scoped evidence object and never occupy this contract.
      - `attested_by` 'Fonteum', required
      - `standard` 'W3C-VC-2.0', required
      - `content_credential` 'C2PA-aligned Content Credentials for facts', required
      - `source` string, nullable, required
      - `as_of` string, nullable, required
      - `attestation_id` integer, nullable, required: Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index.
      - `chain_head_hash` string, nullable, required: Current chain-head content hash. This field is deliberately not named or represented as a signature.
      - `recheck_url` string, uri, required
      - `key_url` string, uri, required: Signing-key directory used by separately exposed chain and witness evidence.
      - `docs_url` string, uri, required

## Other responses

- `400`: Malformed request (invalid JSON, missing query, or query too long).
- `401`: Missing or invalid API key.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/fonteum/apis/fonteum-api.md) · [All operations](https://skmtc.dev/fonteum/apis/fonteum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fonteum/apis/fonteum-api/revisions/334e6e179d0d?raw)