HTTP API

Publish a payload. The body is the payload itself, with $template naming one of the templates. Order of checks: authenticate, rate limits, quota, size cap (4 MB hard, then the template's own), parse, structural safety, schema. The exact bytes are stored.

{ "guid", "url", "template_id", "template_version", "trust_tier": "unverified",
  "content_hash", "byte_size", "created_at" }

The caller's own pages, newest first (limit 1–200). next_before is set when a full page came back; pass it as before for the next.

{ "key_id", "next_before",
  "artifacts": [{ "guid", "url", "template_id", "template_version", "title", "byte_size", "created_at",
                  "trust_tier", "verified_at",
                  "verification"?: { "status", "requested_at", "reviewed_at" } }] }

One page as data: metadata and the stored payload (without $template).

{ "guid", "template_id", "template_version", "trust_tier", "verified_at", "title",
  "content_hash", "created_at", "payload" }

The body the page was published with, exactly as received, as data: for a BetterBench page, the results.json a verifier reproduces. The bytes are spliced into the envelope unchanged, so sha256 of data equals the publisher's body_sha256, also sent as X-Body-SHA256. Pages from before bodies were stored come back re-serialized with X-Body-Verbatim: false.

Ask for a page to be verified. Only the key that published it (E_UNAUTHORIZED), only bench.betterbench.v1 and scan.pwdet.v1 pages (E_VERIFY_INELIGIBLE), one open request per page (E_VERIFY_EXISTS, 409). All fields are optional.

{ "note": "how to reproduce, ≤ 2000 chars",
  "client_checks": [{ "name", "status": "pass|warn|fail", "detail" }],
  "source_sha256": "hex", "body_sha256": "hex", "content_hash": "as returned at publish",
  "l80_version": "1.0.0" }

The server runs the checks on the stored payload. If any fails, the attempt is recorded and closed at once (status rejected, no reviewer), the page stays unverified, and the answer is E_VERIFY_INELIGIBLE (422) with one details entry per failed check. Otherwise the page turns pending and the response is the Verification (201).

The page's latest request, or E_NOT_FOUND.

An array of Verification, oldest first, at most 200. scope=queue (the default) is requests made by other keys, never the caller's own; scope=mine is the caller's own. status filters; omitted or all means every status.

One request, with mine set for the caller.

Verifier keys only (E_NOT_VERIFIER, 403), never on the caller's own request (E_OWN_REQUEST, 403). The request must be open, else E_VERIFY_CLOSED (409). A rejection needs a note. reproduction is optional and stored as sent, except on a pwdet scan (run_class scan): approving one needs pwdet's comparison with template: "scan.pwdet.v1", a scan object and within_tolerance: true, else E_REPRODUCTION_REQUIRED (422).

{ "decision": "verified" | "rejected",
  "note": "required for rejected",
  "reproduction": {
    "betterbench_version": "0.6.1", "model": "Qwen3-8B",
    "notes": { "engine": "vLLM 0.9.3", "hardware": "1x RTX 4090" },
    "runs_per_category": 20, "phases": ["decode", "prefill", "concurrency"],
    "metrics": [{ "label": "Combined decode", "unit": "t/s", "published": 142.4, "reproduced": 139.8,
                  "delta_pct": -1.8, "tolerance_pct": 10, "within": true }],
    "within_tolerance": true, "results_sha256": "hex", "ran_at": "RFC 3339", "l80_version": "1.0.0" } }

Sets the page to verified (with verified_at) or rejected and returns the updated Verification.

[{ id, version, label, schema_url }]

The template's JSON Schema (draft 2020-12).