> ## 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 API: Base URL, Auth, and Error Codes Guide

> The Heretic explain API returns full verdict JSON for a session. Learn how to authenticate, handle errors, and structure requests.

The Heretic explain API is a single HTTP endpoint that returns a complete verdict for any session ID collected by the [Heretic collector](https://www.npmjs.com/package/@heretic-hq/collector). You call it from your server, pass the session ID your client-side collector generated, and receive a structured JSON object telling you exactly what the evidence found — including a human-readable summary, individual signals, and a conclusive flag you can act on directly.

## Base URL

All API requests go to the following base URL:

```
https://edge.heretic.quest
```

## Authentication

Every request must include a valid API key. You can create and rotate keys from your [Heretic dashboard](https://heretic.quest/dashboard/keys). Pass your key as a Bearer token in the `Authorization` header on every request.

```http theme={null}
Authorization: Bearer {your-api-key}
```

**Example request using curl:**

```bash theme={null}
curl -H "Authorization: Bearer $HERETIC_API_KEY" \
  "https://edge.heretic.quest/e?n=SESSION_ID"
```

<Tip>
  Store your API key in an environment variable such as `HERETIC_API_KEY` and never expose it in client-side code. The explain endpoint is intended for server-side use only.
</Tip>

## Rate Limits

The API enforces rate limits and returns `429 Too Many Requests` when you exceed them. To stay within limits, **cache verdict results on your side** — a session ID is immutable once the verdict is produced, so there is no need to re-fetch the same session twice. A simple in-memory or Redis cache keyed by session ID is sufficient for most workloads.

## Error Codes

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `200`  | Verdict returned successfully                                   |
| `401`  | Invalid or missing API key                                      |
| `404`  | Session not found or expired (sessions expire after 15 minutes) |
| `429`  | Rate limit exceeded                                             |

<Tip>
  A `404` response does not always mean a bad session ID — it can also mean the session expired before you fetched it. Sessions live for 15 minutes after collection. Fetch the verdict promptly after your client-side collector completes.
</Tip>

## Next Steps

* [GET /e — Explain Endpoint Reference](/api/explain-endpoint): full request/response reference including code examples
* [Verdict Response Schema](/api/verdict-schema): complete field documentation for the JSON response


## Related topics

- [Heretic Verdict Schema: Complete JSON Field Reference](/api/verdict-schema.md)
- [GET /e Explain Endpoint: Full Request and Response Reference](/api/explain-endpoint.md)
- [Read and Interpret Heretic Explain Endpoint Responses](/integration/reading-verdicts.md)
- [Heretic: Physics-Based Browser Intelligence Platform](/introduction.md)
- [Heretic Quick Start: Collect Sessions and Read Verdicts](/quickstart.md)