> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heretic.quest/llms.txt
> Use this file to discover all available pages before exploring further.

# Heretic Verdict Schema: Complete JSON Field Reference

> Complete field reference for the Heretic verdict JSON response. Covers verdict values, signal structure, family reporting, and the conclusive flag.

Every response from the explain endpoint follows this schema. Use this reference when you write the parsing and enforcement logic on your server — for example, when deciding whether to block an action based on `conclusive`, branch on a specific `verdict` value, or inspect individual `signals` for audit logging.

## Top-Level Fields

<ResponseField name="schema" type="integer" required>
  Response schema version. Currently `7`. The value increments on breaking changes to the response structure. Check this field in production parsers so you can gate on the version you were written against and fail safely if an unexpected version arrives.
</ResponseField>

<ResponseField name="provenance" type="object" required>
  Metadata about the API version that produced this verdict. Useful for bug reports and support tickets.

  <Expandable title="provenance fields">
    <ResponseField name="build" type="string" required>
      Build identifier for the API version that evaluated this session. Example: `"0.0.1+11f956e"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="verdict" type="string" required>
  The ruling for this session. One of `contradicted`, `refused`, `disputed`, `uncontradicted`, or `insufficient`. See the [Verdicts table](#verdicts) below for the full breakdown of what each value means and when to act on it.
</ResponseField>

<ResponseField name="conclusive" type="boolean" required>
  `true` when the verdict is backed by an absolute signal or by two corroborating composite signals from different evidence families. Use this flag as your primary enforcement gate — a `conclusive: true` result means the evidence is strong enough to act on without additional review.
</ResponseField>

<ResponseField name="summary" type="string" required>
  A human-readable, one-to-two sentence explanation of why the verdict was reached. Suitable for internal dashboards, support tooling, or analyst review queues. Example: `"Claimed locale is physically unreachable; transport stack contradicts the claimed OS."`
</ResponseField>

<ResponseField name="contradicting_families" type="string[]" required>
  List of evidence family IDs whose signals actively contradicted the client's claims. Empty when the verdict is anything other than `contradicted`. Possible family IDs: `network-geometry`, `transport-stack`, `tls-construction`, `compute`, `render`, `declared`.
</ResponseField>

<ResponseField name="families" type="object" required>
  Aggregate counts of how many evidence families participated in this session's measurement.

  <Expandable title="families fields">
    <ResponseField name="measured" type="integer" required>
      Number of families that attempted measurement during the session.
    </ResponseField>

    <ResponseField name="reporting" type="integer" required>
      Number of families that returned usable results. When `reporting` is significantly lower than `measured`, the client may have refused measurements — check the `verdict` for `refused`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="signals" type="array" required>
  Individual signals that fired during evaluation. Each entry represents one specific test that produced a result. The array may be empty for `insufficient` verdicts where too few families reported.

  <Expandable title="signal object fields">
    <ResponseField name="id" type="string" required>
      Stable, dot-namespaced signal identifier. The namespace prefix corresponds to the evidence family (e.g. `geo.` for `network-geometry`, `stack.` for `transport-stack`). Example: `"geo.rtt-below-vacuum"`.
    </ResponseField>

    <ResponseField name="tier" type="string" required>
      Signal strength classification. One of:

      * `absolute` — a single signal that is conclusive on its own
      * `composite` — strong signal; two signals from different families make the verdict conclusive
      * `conditional` — meaningful only alongside other signals
      * `weak` — advisory; contributes to context but not to conclusiveness
    </ResponseField>

    <ResponseField name="headline" type="string" required>
      One-line human-readable explanation of what this signal observed. Example: `"RTT 2.1ms; light needs 27.4ms"`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Verdicts

The `verdict` string and `conclusive` boolean work together. Use `conclusive` as your primary enforcement signal and `verdict` for categorisation, logging, and routing.

| Verdict          | `conclusive` | Meaning                                                                                                                                          |
| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contradicted`   | `true`       | One absolute signal, or two corroborating composite signals from different families, found a direct contradiction. Safe to act on automatically. |
| `contradicted`   | `false`      | A contradiction was detected but the evidence has not yet reached the conclusive threshold. Consider flagging for review rather than blocking.   |
| `refused`        | varies       | The client refused one or more required measurements. Treat refusal as a strong negative signal in most enforcement contexts.                    |
| `disputed`       | `false`      | Evidence leans toward contradiction but is not conclusive. Review recommended.                                                                   |
| `uncontradicted` | `false`      | No contradiction was detected across all reporting families.                                                                                     |
| `insufficient`   | `false`      | Too few families reported results to reach a verdict. The session may have been cut short or the collector did not complete its run.             |

<Note>
  The `schema` integer will increment whenever there is a breaking change to this response structure. Always check `schema` in your production parser and handle unexpected versions explicitly — do not silently fall through to default logic.
</Note>

## Related

* [API Overview and Authentication](/api/overview): base URL, authentication, and error handling
* [GET /e — Explain Endpoint Reference](/api/explain-endpoint): request parameters, code examples, and the full sample response


## Related topics

- [GET /e Explain Endpoint: Full Request and Response Reference](/api/explain-endpoint.md)
- [Heretic API: Base URL, Auth, and Error Codes Guide](/api/overview.md)
- [Heretic: Physics-Based Browser Intelligence Platform](/introduction.md)
- [Heretic Signal Reference: IDs, Evidence Families, and Tiers](/reference/signals.md)
- [Heretic Quick Start: Collect Sessions and Read Verdicts](/quickstart.md)