NeuronLens
Browse the documentation
API reference

Integrity Lens endpoints

Every Integrity Lens endpoint: scans, models and approvals, sources, signed reports, webhooks, and the one-call scan.


Two ways to scan:

  • Your organization's scans (/v1/integrity/scans, below): queued, saved to your organization, compared with your approved version, with signed reports. Use these for production and CI.
  • One call (POST /v1/integrity/scan): waits for the result and returns the full engine output. Nothing is saved to your organization.

Every endpoint takes your API key as Authorization: Bearer nl_... or X-API-Key. Requests act in the organization the key was created for; for a key without one, in your first organization (or your personal workspace if you have none). Add ?org=<slug> to choose another one you belong to. What you do on the website and through the API lands in the same organization and counts against the same daily allowance.

POST /v1/integrity/scans

Queue a scan. Answers at once with 202 and the scan in state queued. Counts as one run.

FieldDefaultValues
modelrequiredhf://org/repo or hf://org/repo@revision (branch, tag or commit), public or private
compareapprovedapproved, base (detected from the card, config or name), or another hf:// reference
testsstandardquick, standard, deep (recorded; today all three run the same checks)
run_oncloudcloud (runners come later)
webhooknonean https:// URL we call when the scan finishes
namethe repo iddisplay name when the model is new to your organization
curl -s https://api.neuronlens.com/v1/integrity/scans \
  -H "Authorization: Bearer $NEURONLENS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "hf://acme/kyc-assistant-v3@7d03b11", "compare": "approved", "webhook": "https://ci.acme.com/hooks/neuronlens"}'
# -> {"scan_id": "scn_9f2c41d07a1be3c4", "status": "queued", ...}

s3:// and gs:// answer 422 until cloud buckets are available. A private or gated repo without a connected token finishes failed with error.code = "needs_token".

GET /v1/integrity/scans/{id}

Poll until status is done or failed. Add ?full=1 for the engine's complete integritylens.scan/v1 result under detail.

{
  "scan_id": "scn_9f2c41d07a1be3c4", "status": "done", "model_id": "mdl_51d0e9a2c4b7f310",
  "model": {"ref": "hf://acme/kyc-assistant-v3", "revision": "7d03b11...", "requested_revision": "7d03b11"},
  "compare": "approved",
  "compared_against": {"ref": "hf://acme/kyc-assistant-v3", "revision": "a41c9e0..."},
  "measured_against": {"ref": "hf://meta-llama/Llama-3.1-8B-Instruct", "source": "card"},
  "verdict": "tampered", "confidence": 0.94, "against_approved": "tampered",
  "checks": {"inside": "detected", "behaviour": "not_run", "files": "clean"},
  "changed_layers": [14, 15, 16, 17, 18, 19, 20],
  "engine_state": "Abliterated",
  "versions": {"method": "ilscan-B", "schema": "integritylens.scan/v1", "calibration": null},
  "error": null,
  "report_url": "https://api.neuronlens.com/v1/integrity/scans/scn_9f2c41d07a1be3c4/report"
}
FieldValues
statusqueued, running, done, failed
verdictno_issue, review, tampered, not_assessed
against_approvedmatches_approved, changed, tampered, no_approved_version
scanned_byemail of the person who started the scan (website or API key owner)
channelapp (website) or api
checksinside: detected / clean / not_run; behaviour: not_run today; files (Hugging Face's file scans): clean / flagged / unavailable
changed_layerslayers where the refusal signal fell below half of the base's
error{"code", "message"} when failed: needs_token (private or gated, no token can read it), scanner_unavailable, timeout, internal

In CI, fail the build when verdict is tampered or against_approved is not matches_approved; see Gate a build.

Other endpoints

EndpointUseRole
GET /v1/integrity/scans?model=&status=&mine=&limit=your organization's scans, newest first; mine=1 for only yoursany
GET /v1/integrity/scans/{id}/reportprintable HTML report, signedany
GET /v1/integrity/scans/{id}/report.jsonthe same report as JSON with an Ed25519 signatureany
POST /v1/integrity/verifysend a report.json back: {"valid": true} if it is ours and uneditedany
GET /v1/integrity/report-keyour public key, to verify reports offlineany
POST /v1/integrity/modelsregister a model: {"name", "model": "hf://org/repo"}reviewer
GET /v1/integrity/models, /models/{id}models, approved version, status against it; {id} adds the historyany
POST /v1/integrity/models/{id}/approve{"scan_id"} or {"revision"}; default the latest finished scan. A tampered scan needs "force": true. Loggedreviewer
GET /v1/integrity/sourcesconnected sourcesany
POST /v1/integrity/sources{"kind": "huggingface", "token": "hf_..."}: a read-only token, checked with Hugging Face, stored encryptedadmin
POST /v1/integrity/sources/huggingface/removeremove the tokenadmin
GET /v1/integrity/auditapprovals and source changesany
GET /v1/integrity/whoamiyour organization, role and scans in the last 24 hoursany
GET /v1/integrity/catalog?family=&q=scannable public Hub modelsany
GET /v1/integrity/base?model=family, level and detected base before scanningany

Roles: any = viewer and up; reviewer = member, admin or owner; admin = admin or owner.

Only POST /scans and POST /scan count as runs.

Errors

StatusWhen
401no API key, or an unknown one
403your role cannot do this (for example a viewer starting a scan)
404the scan or model is not in your organization
422a malformed model reference; a cloud bucket or runner (not available yet); a webhook that is not a public https:// URL; a Hugging Face token that is invalid or can write
429your daily allowance, or your organization's 50 scans per 24 hours or 10 waiting

Gateway errors shared by every product are in Errors.

Webhooks

When a scan with a webhook finishes, we POST {"event": "scan.finished", "scan": {...}} (the object above) to it, retrying twice. The X-NeuronLens-Signature header is the base64 Ed25519 signature of the raw body; check it with the key from GET /v1/integrity/report-key. Webhooks must be public https:// URLs.

Signed reports

report.json is {"report": {...}, "signature": {"alg": "Ed25519", "key_id", "value"}}. The signature covers the report serialized as JSON with sorted keys and no spaces. In Python:

import base64, json, requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

env = json.load(open("scn_9f2c41d07a1be3c4.json"))
key = requests.get("https://api.neuronlens.com/v1/integrity/report-key",
                   headers={"Authorization": f"Bearer {API_KEY}"}).json()
body = json.dumps(env["report"], sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
Ed25519PublicKey.from_public_bytes(base64.b64decode(key["public_key"])).verify(
    base64.b64decode(env["signature"]["value"]), body)   # raises if edited

POST /v1/integrity/scan

Scan a Hugging Face model and return whether its safety has been stripped. Counts as one run, except a stored result ("cached": true) and an Unknown verdict.

A first scan of a model takes about a minute; set your client timeout to at least 11 minutes.

Body

FieldTypeDefaultDescription
modelstring org/namerequiredpublic Hugging Face model (private ones: use POST /scans); a full https://huggingface.co/... URL also works
parentstring org/namefrom the model cardthe base it was fine-tuned from
refreshbooleanfalseignore a stored result for this revision and scan again

Response (integritylens.scan/v1)

FieldDescription
modelid, revision, family, parent_on_card, calibrated_base, mode
verdictstate (Intact / Degraded / Removed / Unknown), label, summary, reason, confidence, predicted_harmful_rate, predicted_range
positionact_damage on the calibration curve, with intact_below and removed_from
evidenceactivation_damage, targeting_ratio, weight_removal, how, mode
layersper-layer refusal_signal_vs_base and weight_change_on_refusal
checkswhat ran and what did not
calibrationthe curve behind the verdict
computegpu, timings, cached
cachedtrue when this is a stored result

Fields that do not apply are null. See Verdicts and evidence.

Examples

curl https://api.neuronlens.com/v1/integrity/scan \
  -H "X-API-Key: $NEURONLENS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "google/gemma-3-4b-it"}'
{
  "schema": "integritylens.scan/v1",
  "model": {"id": "google/gemma-3-4b-it", "revision": "093f9f388b31de276ce2de164bdc2081324b9767",
            "family": "Gemma 3 4B", "parent_on_card": "google/gemma-3-4b-pt",
            "calibrated_base": "google/gemma-3-4b-it", "mode": "standalone"},
  "verdict": {"state": "Intact", "label": "NO ISSUE DETECTED", "confidence": 1.0,
              "summary": "Refusal behaviour reads as intact. The model's internal refusal signal matches the clean base.",
              "predicted_harmful_rate": 0.1072, "predicted_range": [0.0572, 0.1572]},
  "evidence": {"activation_damage": {"value": -0.0003}, "targeting_ratio": null, "weight_removal": null,
               "weights_skipped_because": "This is the calibrated base itself.", "mode": "Standalone"},
  "compute": {"activation_s": 6.3, "total_s": 29.7, "cached": false}
}
const r = await fetch("https://api.neuronlens.com/v1/integrity/scan", {
  method: "POST",
  headers: { "X-API-Key": process.env.NEURONLENS_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "mlabonne/gemma-3-4b-it-abliterated-v2" }),
  signal: AbortSignal.timeout(660_000),
});
const res = await r.json();
console.log(res.verdict.state, res.evidence.how);   // Removed, "...the signature of abliteration."

GET /v1/integrity/families

The supported families, with level and validation. Not counted. See Supported models.

[{"key": "gemma3-2560", "label": "Gemma 3 4B", "base": "google/gemma-3-4b-it", "aliases": ["gemma3_text-2560"],
  "level": "C", "weights_validated": true}]