Tenant verdict endpoint

curl --request GET \
  --url https://api.example.com/v1/verdict/{requestId}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/verdict/{requestId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/verdict/{requestId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/verdict/{requestId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

GET

verdict

{requestId}

Tenant verdict endpoint

curl --request GET \
  --url https://api.example.com/v1/verdict/{requestId}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/verdict/{requestId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/verdict/{requestId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/verdict/{requestId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Call the tenant verdict endpoint from your backend:

GET https://heretic.quest/v1/verdict/{requestId}
Authorization: Bearer hrtc_sk_<32 lowercase hex>

The secret key scopes the read to one site. Keep it out of browser code.

Request ID

Use the raw 32-character lowercase hexadecimal request ID returned by ordinary collection. The endpoint tolerates one legacy req_ prefix for compatibility, but new integrations must pass the raw ID unchanged.

Server example

const VERDICT_ORIGIN = 'https://heretic.quest';

export async function readHereticVerdict(requestId) {
  const response = await fetch(
    `${VERDICT_ORIGIN}/v1/verdict/${encodeURIComponent(requestId)}`,
    {
      headers: {
        authorization: `Bearer ${process.env.HERETIC_VERDICT_KEY}`,
      },
    },
  );

  if (response.status === 200) {
    return { state: 'available', value: await response.json() };
  }

  if (response.status === 404) {
    return { state: 'unavailable' };
  }

  if (response.status === 401) {
    throw new Error(
      'Heretic verdict key is missing, malformed, unknown, or revoked',
    );
  }

  throw new Error(`Heretic verdict read failed with HTTP ${response.status}`);
}

A curl request uses the raw nonce:

curl -H "Authorization: Bearer $HERETIC_VERDICT_KEY" "https://heretic.quest/v1/verdict/0123456789abcdef0123456789abcdef"

Status codes

Status	Meaning
`200`	A row exists and belongs to the authenticated key’s site.
`401`	The key is missing, malformed, unknown, or revoked.
`404`	The ID is missing, invalid, foreign, archived, deleted, pruned, or belongs to a ZDR request.

The endpoint returns plain text for 401 and 404. Cross-site and missing IDs deliberately share 404. The route defines no application-level 429 contract. Treat other statuses as unexpected HTTP failures, not assessment verdicts.

Availability

Successful ordinary collection means D1 acknowledged a tenant-visible commit. The authenticated owning tenant can retrieve the returned ID immediately. Projection failure makes collection fail instead of returning a request ID. The 60-second settlement threshold and 30-second sweep apply only to local NDJSON persistence. ZDR creates no tenant row.

Success response

A 200 response returns tenant API version 1:

{
  "api_version": "1",
  "request_id": "0123456789abcdef0123456789abcdef",
  "verdict": "disputed",
  "conclusive": false,
  "insufficient_reason": null,
  "refused": false,
  "summary": "Human-readable assessment summary",
  "signals": [
    {
      "id": "stack.os-contradiction",
      "tier": "composite",
      "family": "transport-stack",
      "headline": "Human-readable finding headline",
      "detail": "Human-readable finding detail"
    }
  ],
  "families": [
    {
      "family": "network-geometry",
      "status": "consistent",
      "highest_tier": null,
      "coverage": { "state": "measured" }
    },
    {
      "family": "transport-stack",
      "status": "contradicted",
      "highest_tier": "composite",
      "coverage": { "state": "measured" }
    },
    {
      "family": "transport-reachability",
      "status": "consistent",
      "highest_tier": null,
      "coverage": { "state": "measured" }
    },
    {
      "family": "tls-construction",
      "status": "consistent",
      "highest_tier": null,
      "coverage": { "state": "measured" }
    },
    {
      "family": "http-construction",
      "status": "consistent",
      "highest_tier": null,
      "coverage": { "state": "measured" }
    },
    {
      "family": "compute",
      "status": "consistent",
      "highest_tier": null,
      "coverage": { "state": "measured" }
    }
  ],
  "provenance": {
    "schema": 10,
    "build": "0.0.1+f19fb27",
    "ruleset_revision": 6,
    "compute_probe_version": 2
  },
  "network": {
    "asn": 64500,
    "country": "US",
    "description": "Example network",
    "classification": "access"
  },
  "identity": {
    "version": 2,
    "instance": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "machine": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "tier": {
      "instance": "absolute",
      "machine": "conditional"
    },
    "components": {
      "display": "1920x1080@2",
      "cores": 8,
      "platform": "MacIntel",
      "timezone": "America/New_York"
    }
  },
  "edge": "waw-01",
  "created_at": 1787700000000,
  "ingested_at": 1787700000500
}

The prose and sample values are illustrative. The six family reports are part of the current assessment projection. network, identity, provenance, edge, and timestamps can be null when the stored row lacks valid values. Inside a non-null identity object, missing IDs and components are omitted. See Tenant verdict schema for every field.

Projection boundary

The endpoint does not return the full edge assessment or session. It omits:

the full session and raw measured or declared claims
raw IP and detailed transport records
geometry arithmetic
the full concealment report, apart from projected network classification
the sensor report and per-finding sensor admissions
contradicting_families
each family report’s internal signal-ID list

A tenant secret key authorizes this projection. It is not an edge operator credential.

Stable fields

Use documented IDs, enums, booleans, versions, provenance, and timestamps as program inputs. Treat summary, signal headline, signal detail, network descriptions, and coverage reasons as prose. The endpoint reports an assessment. It does not prescribe a consequence.

Get started

Understand Heretic

Integrate

Reference

Manage and troubleshoot

Tenant verdict endpoint

Request ID

Server example

Status codes

Availability

Success response

Projection boundary

Stable fields

​Request ID

​Server example

​Status codes

​Availability

​Success response

​Projection boundary

​Stable fields

Request ID

Server example

Status codes

Availability

Success response

Projection boundary

Stable fields