GET /e Explain Endpoint: Full Request and Response Reference

The explain endpoint is the primary API surface of Heretic. You pass a session ID — generated by the @heretic-hq/collector package running in your user’s browser — and the edge returns a complete ruling: a verdict, the individual signals that fired, the evidence families that measured the session, and a human-readable summary you can surface in your own tooling.

Request

Method: GET
URL: https://edge.heretic.quest/e

Query Parameters

string

required

The session ID returned by the Heretic collector. The collector exposes this as a string after the measurement run completes. Example: 9f2c41ab.

Headers

string

required

Your Heretic API key, passed as a Bearer token: Bearer {your-api-key}. You can create keys at heretic.quest/dashboard/keys.

Code Examples

curl:

curl -H "Authorization: Bearer $HERETIC_API_KEY" \
  "https://edge.heretic.quest/e?n=9f2c41ab"

TypeScript (fetch):

const res = await fetch(
  `https://edge.heretic.quest/e?n=${sessionId}`,
  { headers: { Authorization: `Bearer ${process.env.HERETIC_API_KEY}` } }
);
const verdict = await res.json();

Response

A successful 200 response returns a JSON object conforming to the Verdict Response Schema. The example below is a real session showing a contradicted verdict with two composite signals:

{
  "schema": 7,
  "provenance": { "build": "0.0.1+11f956e" },
  "verdict": "contradicted",
  "conclusive": true,
  "summary": "Claimed locale is physically unreachable; transport stack contradicts the claimed OS.",
  "contradicting_families": ["network-geometry", "transport-stack"],
  "families": { "measured": 6, "reporting": 6 },
  "signals": [
    {
      "id": "geo.rtt-below-vacuum",
      "tier": "composite",
      "headline": "RTT 2.1ms; light needs 27.4ms"
    },
    {
      "id": "stack.os-contradiction",
      "tier": "composite",
      "headline": "SYN by Linux 5.x; UA claims macOS 15"
    }
  ]
}

Session Expiry

Sessions expire 15 minutes after they are collected by the edge. If you request a session ID after that window, the API returns 404. Fetch the verdict promptly after your collector run completes — or immediately upon receiving the session ID from the client.

Do not store raw session IDs for delayed lookup. Either fetch the verdict at collection time and cache the result, or fetch within the 15-minute window. A cached verdict is permanent; an unfetched session is not.

API Overview and Authentication: base URL, authentication, and error code reference
Verdict Response Schema: complete documentation of every field in the response JSON

​Request

​Query Parameters

​Headers

​Code Examples

​Response

​Session Expiry

​Related

Request

Query Parameters

Headers

Code Examples

Response

Session Expiry

Related