> ## 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 Quick Start: Collect Sessions and Read Verdicts

> Install the @heretic-hq/collector package, collect a browser session ID, and call the explain endpoint to read your first verdict.

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.

<Steps>
  <Step title="Request access and sign in to the dashboard">
    Heretic is currently in early access. Head to [heretic.quest/dashboard](https://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.
  </Step>

  <Step title="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](https://heretic.quest/dashboard/keys) and copy the secret API key. You will use this key to authenticate server-side calls to the explain endpoint.

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

  <Step title="Install the collector">
    Add the `@heretic-hq/collector` package to your project with your preferred package manager.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @heretic-hq/collector
      ```

      ```bash yarn theme={null}
      yarn add @heretic-hq/collector
      ```

      ```bash pnpm theme={null}
      pnpm add @heretic-hq/collector
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    ```typescript theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    GET https://edge.heretic.quest/e?n=sess_01J3KR8VMNPQ2XTWCBD7F9GAE4
    Authorization: Bearer sk_live_YOUR_API_KEY
    ```

    ```typescript theme={null}
    // 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:

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Step>
</Steps>

<Note>
  **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.
</Note>

<Tip>
  Want to see Heretic fire against a real browser without writing any code? Visit [probe.heretic.quest](https://probe.heretic.quest) to run a live probe session in your current browser and inspect the raw signals and verdict it produces.
</Tip>


## Related topics

- [Heretic: Physics-Based Browser Intelligence Platform](/introduction.md)
- [Heretic FAQ: Integration, Verdicts, Privacy, and Access](/reference/faq.md)
- [How Heretic Measures Browser Integrity with Physics](/how-it-works.md)
- [Read and Interpret Heretic Explain Endpoint Responses](/integration/reading-verdicts.md)
- [Heretic Privacy: Data Collection, Retention, and Deletion](/reference/privacy.md)