The Heretic explain API is a single HTTP endpoint that returns a complete verdict for any session ID collected by the Heretic 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:
Authentication
Every request must include a valid API key. You can create and rotate keys from your Heretic dashboard. Pass your key as a Bearer token in the Authorization header on every request.
Example request using curl:
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.
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
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.
Next Steps
