Heretic Quick Start: Collect Sessions and Read Verdicts

By the end of this guide you will have the Heretic collector running on your page, a live session flowing into the pipeline, and a verdict JSON response arriving at your server — all without touching your DNS or routing a single byte through a Heretic proxy.

Request access and sign in to the dashboard

Heretic is currently in early access. Head to heretic.quest/dashboard and sign in with your account. If you do not have an account yet, request access from the same page — the apostate tier is free and gives you the full signal catalogue immediately upon approval.

Create a site and copy your API key

Inside the dashboard, create a new site for the domain you want to protect. Once the site is created, navigate to heretic.quest/dashboard/keys and copy the secret API key. You will use this key to authenticate server-side calls to the explain endpoint.

Your API key authorises verdict reads and carries your billing identity. Never expose it in client-side code or commit it to source control.

Install the collector

Add the @heretic-hq/collector package to your project with your preferred package manager.

npm install @heretic-hq/collector

yarn add @heretic-hq/collector

pnpm add @heretic-hq/collector

Initialise the collector on your page

Import and initialise the collector as early as possible in your page lifecycle — ideally before any user-interaction handlers fire. The collector generates a unique session ID, runs all probes out-of-band against your origin, and returns the session ID you will pass to your server.

import { createCollector } from '@heretic-hq/collector';

const heretic = createCollector({
  siteId: 'site_01HXYZ_YOUR_SITE_ID',
});

// sessionId is a UUID you attach to your form submission,
// checkout payload, login request, or any server action.
const { sessionId } = await heretic.collect();

console.log('Heretic session:', sessionId);
// e.g. "sess_01J3KR8VMNPQ2XTWCBD7F9GAE4"

Pass sessionId to your server in whatever way fits your stack — a hidden form field, a request header such as X-Heretic-Session, or a JSON body field.

Read the verdict on your server

On your server, call the explain endpoint with the session ID before you trust the request. The endpoint returns a full verdict object you can act on immediately.

GET https://edge.heretic.quest/e?n=sess_01J3KR8VMNPQ2XTWCBD7F9GAE4
Authorization: Bearer sk_live_YOUR_API_KEY

// Node.js / TypeScript example
const response = await fetch(
  `https://edge.heretic.quest/e?n=${sessionId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.HERETIC_API_KEY}`,
    },
  }
);

const verdict = await response.json();

if (verdict.verdict === 'contradicted') {
  // Block, challenge, or flag the request
}

A successful response looks like this:

{
  "schema": 7,
  "session_id": "sess_01J3KR8VMNPQ2XTWCBD7F9GAE4",
  "verdict": "contradicted",
  "conclusive": true,
  "summary": "The session declares a residential Chrome on macOS but presents a Linux datacenter TCP stack, a mismatched TLS extension order consistent with a headless runtime, and an RTT 14 ms below the speed-of-light floor for the claimed geography.",
  "contradicting_families": [
    "network-geometry",
    "transport-stack",
    "tls-construction"
  ],
  "families": {
    "network-geometry": "contradicted",
    "transport-stack": "contradicted",
    "tls-construction": "contradicted",
    "compute": "uncontradicted",
    "render": "insufficient",
    "declared": "contradicted"
  },
  "signals": [
    {
      "id": "net.rtt_floor_delta",
      "tier": "absolute",
      "headline": "RTT 14 ms below speed-of-light floor for declared origin city"
    },
    {
      "id": "tcp.options_fingerprint",
      "tier": "absolute",
      "headline": "TCP options sequence matches Linux 5.x datacenter profile, not macOS Sequoia"
    },
    {
      "id": "tls.extension_order",
      "tier": "composite",
      "headline": "TLS ClientHello extension order inconsistent with Chrome 124 on macOS"
    },
    {
      "id": "tls.grease_pattern",
      "tier": "composite",
      "headline": "GREASE values absent; expected in genuine Chrome 124"
    },
    {
      "id": "quic.reachability",
      "tier": "conditional",
      "headline": "QUIC path unreachable from declared network type"
    }
  ]
}

Apostate tier — free early access. The apostate plan gives you full access to the entire Heretic signal catalogue at no cost during early access. There are no signal limits, no sampled verdicts, and no time-boxed trial. When paid tiers launch, you will receive advance notice before anything changes.

Want to see Heretic fire against a real browser without writing any code? Visit probe.heretic.quest to run a live probe session in your current browser and inspect the raw signals and verdict it produces.

Get Started

Core Concepts

Integration

Dashboard

Reference

Heretic Quick Start: Collect Sessions and Read Verdicts